@mapples/inlang 1.0.2 → 1.1.1

package/README.md

@@ -1,146 +1,454 @@
-# @mapples/inlang
+# @mapples/types
 
-Internal language utilities for the Mapples Open Kit. This package provides parsing and evaluation helpers for "this" references, dimension strings, and condition strings used across the Mapples ecosystem (e.g. data bindings, visibility conditions, layout).
-
-## Features
-
-- **This references** – Parse and detect `"this"` and `"this::n"` style action/context references
-- **Data this** – Parse `(this)` and dot-separated paths for data binding
-- **Dimensions** – Parse dimension strings (e.g. `"w::50"`, `"height::100"`) for width/height
-- **Conditions** – Parse and evaluate condition strings (`dataProp::condition::value`) for visibility and logic
-- **TypeScript** – Full type definitions and TSDoc
+TypeScript type definitions for the Mapples Open Kit. This package provides all the core type definitions used across the Mapples ecosystem, including component registration, form configurations, and asset management.
 
 ## Installation
 
 ```bash
-npm install @mapples/inlang
+npm install @mapples/types
 # or
-yarn add @mapples/inlang
+yarn add @mapples/types
 ```
 
 ## Overview
 
-`@mapples/inlang` is used by other Mapples packages (e.g. render, form, ui) to interpret configuration strings. It does not depend on React or React Native.
+The `@mapples/types` package contains essential TypeScript interfaces and types that define the structure and behavior of components, forms, and assets in the Mapples system. These types ensure type safety and provide clear contracts for developers working with the Mapples Open Kit.
 
-## API Reference
+## Core Types
 
-### Constants
+### Action Types
 
-- **`FN_SEPARATOR`** – `'::'` – Separator used in "this", dim, and condition strings
-- **`DATA_THIS`** – `'(this)'` – Prefix for data-context reference (entire state)
-- **`DOT_SEPARATOR`** – `'.'` – Separator for object paths (e.g. `user.name`)
+#### `Action`
 
-### This (action/context references)
+Represents a user action that occurred in the application. Actions are used for tracking user interactions, analytics, and state management.
 
-- **`This`** – Type: `['this', string?]`
-- **`isThis(value?)`** – Returns whether the string matches `"this"` or `"this::n"`
-- **`isDataThis(value?)`** – Returns whether the string starts with `(this)`
-- **`parseDataThis(value)`** – Strips `(this)` and splits by dot (path segments)
-- **`parseThis(value?)`** – Parses to `['this', n?]` (e.g. `"this::2"` → `['this', '2']`)
+```typescript
+interface Action {
+  time: number; // Timestamp when the action occurred (in milliseconds since epoch)
+  type?: string; // Optional string identifier for the type of action
+  payload?: ActionPayload; // Optional payload containing additional data about the action
+}
+```
 
-### Dims (dimension strings)
+#### `ActionPayload`
 
-- **`DimType`** – `'width' | 'height'`
-- **`Dims`** – `[DimType, number]` (e.g. `['width', 0.5]` for 50%)
-- **`DimsString`** – `'w' | 'h' | 'width' | 'height'`
-- **`parseDims(dim)`** – Parses strings like `"w::50"` or `"height::100"` to `[type, 0..1]` or `null`
+Represents the payload data that can be attached to an action.
 
-### State (conditions)
+```typescript
+interface ActionPayload {
+  originalEventData?: any[]; // Original event data from the source event
+  data?: any; // Custom data payload specific to the action
+}
+```
 
-#### Types
+**Example:**
 
-- **`Conditions`** – Enum: `equals` (`'eq'`), `notEquals` (`'neq'`)
-- **`SimpleCondition`** – `${string}::${Conditions}::${string}`
-- **`BoolCondition`** – Condition string with `'true'` or `'false'` as value
-- **`ConditionFunc`** – `(a, b) => boolean`
-- **`ValueType`** – `'string' | 'number' | 'boolean' | 'dataProp'`
-- **`ParseConditionResult`** – `{ dataProp, condition, valueProp, valueType }`
+```typescript
+import { Action, ActionPayload } from '@mapples/types';
+
+const userAction: Action = {
+  time: Date.now(),
+  type: 'BUTTON_PRESSED',
+  payload: {
+    data: { buttonId: 'submit', userId: '123' },
+    originalEventData: ['button', 'press', { x: 100, y: 200 }],
+  },
+};
+```
+
+### Mapplet Types
 
-#### Regexp
+#### `MappletType<State>`
 
-- **`ConditionStringRegExp`** – Regex used to split condition strings on `::` (respecting quoted segments)
+Represents the configuration interface for a Mapplet application. A Mapplet is a self-contained application that can be embedded or run standalone.
 
-#### Utils
+```typescript
+interface MappletType<State extends object = object> {
+  state?: State; // Optional initial state object for the Mapplet
+  onAction?: (action: Action) => void; // Optional callback function to handle actions
+}
+```
 
-- **`toConditionString(...values)`** – Joins values with `FN_SEPARATOR`
-- **`parseConditionString(value)`** – Splits a condition string into parts (valueType default `'string'`)
-- **`parseCondition(value)`** – Parses `SimpleCondition | BoolCondition` into `ParseConditionResult` (handles booleans and quoted types)
-- **`isCondition(value)`** – Type guard for valid condition strings
-- **`toBool(value)`** – Converts string/boolean to boolean (`"true"` → true)
-- **`toNumber(value)`** – Converts string/boolean to number (booleans → 0/1)
-- **`parseJoin(key?)`** – Splits key by `;` and removes newlines (for multi-key data props)
+**Example:**
 
-#### Conditions (evaluators)
+```typescript
+import { MappletType, Action } from '@mapples/types';
+
+interface MyAppState {
+  user: { name: string; email: string };
+  settings: { theme: string };
+}
+
+const myMapplet: MappletType<MyAppState> = {
+  state: {
+    user: { name: 'John', email: 'john@example.com' },
+    settings: { theme: 'dark' },
+  },
+  onAction: (action: Action) => {
+    console.log('Mapplet action:', action);
+    // Handle analytics, logging, etc.
+  },
+};
+```
 
-- **`eq`** – `(a, b) => a === b`
-- **`notEq`** – `(a, b) => a !== b`
-- **`conditionMap`** – `Record<Conditions, ConditionFunc>` mapping enum to functions
+### Asset Types
 
-## Usage examples
+#### `AssetType`
+
+Represents the different types of assets that can be used in the Mapples system.
 
 ```typescript
-import {
-  isThis,
-  isDataThis,
-  parseDataThis,
-  parseThis,
-  parseDims,
-  DATA_THIS,
-  FN_SEPARATOR,
-} from '@mapples/inlang';
+type AssetType = 'image' | 'video' | 'icon' | 'font' | 'json';
+```
+
+**Example:**
+
+```typescript
+import { AssetType } from '@mapples/types';
+
+const imageAsset: AssetType = 'image';
+const videoAsset: AssetType = 'video';
+```
+
+### Component Types
+
+#### `RegisteredComponent<T>`
+
+Defines the structure for registering components in the Mapples component system. This interface contains all the metadata needed to make a component available in the visual editor.
+
+```typescript
+interface RegisteredComponent<T extends object = object> {
+  type: string; // Unique component identifier
+  groupId: string; // Group this component belongs to
+  label: string; // Display name
+  Component: ComponentType<PropsWithChildren<T>>; // React component
+  Icon: ComponentType<SvgProps>; // Icon for component palette
+  initialProps: T; // Default props
+  styleKeys: StyleKey[]; // Available style properties
+  props: PropsFormField[]; // Property form fields
+  actionProps: string[]; // Action-triggering properties
+  hidden?: boolean; // Hide from palette
+  hasChildren?: boolean; // Can contain children
+}
+```
+
+**Example:**
+
+```typescript
+import { RegisteredComponent } from '@mapples/types';
+
+interface ButtonProps {
+  text: string;
+  disabled?: boolean;
+  onPress?: () => void;
+}
+
+const buttonComponent: RegisteredComponent<ButtonProps> = {
+  type: 'Button',
+  groupId: 'inputs',
+  label: 'Button',
+  Component: Button,
+  Icon: ButtonIcon,
+  initialProps: { text: 'Click me' },
+  styleKeys: [backgroundColorStyle, textColorStyle],
+  props: [textField, disabledField],
+  actionProps: ['onPress'],
+};
+```
+
+#### `RegisteredComponentsGroup`
+
+Represents a group of components in the component palette.
+
+```typescript
+interface RegisteredComponentsGroup {
+  id: string; // Unique group identifier
+  label: string; // Display name
+  Icon: ComponentType<SvgProps>; // Group icon
+}
+```
+
+#### `RegisteredComponents`
+
+A registry mapping component types to their definitions.
+
+```typescript
+type RegisteredComponents = Record<string, RegisteredComponent>;
+```
+
+#### `StyleKey`
+
+Defines a style property configuration.
+
+```typescript
+interface StyleKey {
+  label: string; // Human-readable label
+  value: string; // CSS property name
+  forms: StyleFormType[]; // Applicable form types
+}
+```
+
+### Form Types
+
+#### `StyleFormType`
+
+Enum representing different categories of style forms.
 
-// This
-isThis('"this"');        // true
-isThis('"this::1"');      // true
-parseThis('"this::2"');  // ['this', '2']
+```typescript
+enum StyleFormType {
+  Dimension = 'Dimension', // Width, height, min/max dimensions
+  Image = 'Image', // Background images, object fit
+  Text = 'Text', // Text color, alignment
+  Typography = 'Typography', // Font family, size, weight
+  Position = 'Position', // Top, left, right, bottom
+  Surface = 'Surface', // Background color, opacity
+  ScrollSurface = 'ScrollSurface', // Scrollable surface properties
+  Borders = 'Borders', // Border width, color, radius
+  Shadow = 'Shadow', // Box shadow, elevation
+  Spacing = 'Spacing', // Margin, padding
+  Svg = 'Svg', // SVG-related properties
+}
+```
+
+#### `PropsFormType`
+
+Enum for property form field types.
+
+```typescript
+enum PropsFormType {
+  Text = 'Text', // Text input field
+  Select = 'Select', // Single selection dropdown
+  Switch = 'Switch', // Boolean toggle
+  MultiSelect = 'MultiSelect', // Multiple selection dropdown
+}
+```
 
-// Data this
-isDataThis('(this)');           // true
-isDataThis('(this).user.name'); // true
-parseDataThis('(this).user.name'); // ['user', 'name']
+#### `PropsFormField`
 
-// Dims
-parseDims('"w::50"');   // ['width', 0.5]
-parseDims('"h::100"');  // ['height', 1]
-parseDims('"width"');   // ['width', 1]
+Configuration for component property form fields.
+
+```typescript
+interface PropsFormField {
+  propsKey: string; // Property key in component props
+  label: string; // Form field label
+  options?: PropsFormFieldOptions; // Options for select fields
+  type: PropsFormType; // Form field type
+  dataProp?: boolean; // Can be bound to data sources
+}
+```
+
+**Example:**
+
+```typescript
+import { PropsFormField, PropsFormType } from '@mapples/types';
+
+const textField: PropsFormField = {
+  propsKey: 'text',
+  label: 'Button Text',
+  type: PropsFormType.Text,
+};
+
+const sizeField: PropsFormField = {
+  propsKey: 'size',
+  label: 'Size',
+  type: PropsFormType.Select,
+  options: [
+    { label: 'Small', value: 'sm' },
+    { label: 'Medium', value: 'md' },
+    { label: 'Large', value: 'lg' },
+  ],
+};
 ```
 
+#### `PropsFormFieldOption`
+
+Represents an option in select/multi-select fields.
+
+```typescript
+interface PropsFormFieldOption {
+  label: string; // Display text
+  value: string; // Stored value
+}
+```
+
+#### `PropsFormFieldOptions`
+
+Union type for form field options.
+
+```typescript
+type PropsFormFieldOptions =
+  | PropsFormFieldOption[] // Array of options
+  | 'typography' // Special typography type
+  | AssetType; // Asset type for asset selection
+```
+
+#### `ActionFormProps`
+
+Configuration for action properties.
+
+```typescript
+interface ActionFormProps {
+  propsKey: string; // Action property key
+  label: string; // Form field label
+}
+```
+
+#### `PropsFieldConfig`
+
+Mapping of form types to their React components.
+
+```typescript
+type PropsFieldConfig = Record<PropsFormType, ComponentType<PropsFormField>>;
+```
+
+## Usage Examples
+
+### Registering a Component
+
 ```typescript
 import {
-  parseCondition,
-  isCondition,
-  toBool,
-  toNumber,
-  Conditions,
-  conditionMap,
-} from '@mapples/inlang';
+  RegisteredComponent,
+  PropsFormField,
+  PropsFormType,
+  StyleFormType,
+  StyleKey,
+} from '@mapples/types';
+
+// Define component props
+interface MyButtonProps {
+  text: string;
+  variant: 'primary' | 'secondary';
+  disabled?: boolean;
+}
+
+// Create style keys
+const backgroundColorStyle: StyleKey = {
+  label: 'Background Color',
+  value: 'backgroundColor',
+  forms: [StyleFormType.Surface],
+};
+
+// Create form fields
+const textField: PropsFormField = {
+  propsKey: 'text',
+  label: 'Button Text',
+  type: PropsFormType.Text,
+};
+
+const variantField: PropsFormField = {
+  propsKey: 'variant',
+  label: 'Variant',
+  type: PropsFormType.Select,
+  options: [
+    { label: 'Primary', value: 'primary' },
+    { label: 'Secondary', value: 'secondary' },
+  ],
+};
+
+// Register the component
+const myButtonComponent: RegisteredComponent<MyButtonProps> = {
+  type: 'MyButton',
+  groupId: 'custom',
+  label: 'My Button',
+  Component: MyButton,
+  Icon: MyButtonIcon,
+  initialProps: {
+    text: 'Click me',
+    variant: 'primary',
+  },
+  styleKeys: [backgroundColorStyle],
+  props: [textField, variantField],
+  actionProps: ['onPress'],
+};
+```
+
+### Creating a Component Group
 
-const r = parseCondition('user.age::eq::18' as any);
-// r.dataProp === 'user.age', r.condition === Conditions.equals, r.valueProp === '18'
+```typescript
+import { RegisteredComponentsGroup } from '@mapples/types';
 
-const br = parseCondition('user.active::eq::true' as any);
-// br.valueProp === true, br.valueType === 'boolean'
+const customGroup: RegisteredComponentsGroup = {
+  id: 'custom',
+  label: 'Custom Components',
+  Icon: CustomIcon,
+};
+```
 
-isCondition('user.role::eq::admin'); // true
-toBool('true');  // true
-toNumber('42');  // 42
+### Working with Form Fields
 
-const fn = conditionMap[Conditions.equals];
-fn(1, 1); // true
+```typescript
+import {
+  PropsFormField,
+  PropsFormType,
+  PropsFormFieldOptions,
+} from '@mapples/types';
+
+// Text field
+const nameField: PropsFormField = {
+  propsKey: 'name',
+  label: 'Name',
+  type: PropsFormType.Text,
+};
+
+// Select field with options
+const statusField: PropsFormField = {
+  propsKey: 'status',
+  label: 'Status',
+  type: PropsFormType.Select,
+  options: [
+    { label: 'Active', value: 'active' },
+    { label: 'Inactive', value: 'inactive' },
+    { label: 'Pending', value: 'pending' },
+  ],
+};
+
+// Asset selection field
+const imageField: PropsFormField = {
+  propsKey: 'image',
+  label: 'Image',
+  type: PropsFormType.Select,
+  options: 'image', // AssetType
+};
+
+// Typography field
+const fontField: PropsFormField = {
+  propsKey: 'font',
+  label: 'Font',
+  type: PropsFormType.Select,
+  options: 'typography',
+};
 ```
 
-## Integration
+## Integration with Other Packages
 
-Used by:
+This types package is used throughout the Mapples ecosystem:
 
-- **@mapples/render** – Data props and condition-based visibility
-- **@mapples/form** – Field bindings and conditional logic
-- **@mapples/ui** – Component props and layout hints
+- **@mapples/action**: Uses `Action` and `ActionPayload` types for action management
+- **@mapples/state**: Uses state-related types for state management
+- **@mapples/ui**: Uses `RegisteredComponent` and related types for component registration
+- **@mapples/form**: Uses `PropsFormField` and form-related types for property editing
+- **@mapples/style**: Uses `StyleKey` and `StyleFormType` for styling configuration
+- **@mapples/render**: Uses component types for rendering components
 
-## License
+## Type Safety
 
-MIT
+All types in this package are designed to provide maximum type safety and IntelliSense support. When working with Mapples components, you'll get:
 
-## Author
+- Autocomplete for all properties
+- Type checking for component props
+- Validation for form field configurations
+- IntelliSense for style properties
 
-Oleksandr Soloviov – [mapples.org](https://mapples.org/people/olek_soloviov)
+## Contributing
+
+When adding new types to this package:
+
+1. Follow the existing naming conventions
+2. Add comprehensive TSDoc comments
+3. Include usage examples
+4. Update this README with new types
+5. Ensure all types are exported from the main index file
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
-/** Separator used in "this", dim, and condition strings. @public */
+/** Separator used between parts of function-call and condition strings (e.g. `"key::value"`). */
 export declare const FN_SEPARATOR = "::";
-/** Prefix for data-context reference (entire state). @public */
+/** Prefix token that identifies a `(this)` data reference in inline-lang expressions. */
 export declare const DATA_THIS = "(this)";
-/** Separator for object paths (e.g. user.name). @public */
+/** Separator used when splitting dot-notation property paths. */
 export declare const DOT_SEPARATOR = ".";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,gEAAgE;AAChE,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC,2DAA2D;AAC3D,eAAO,MAAM,aAAa,MAAM,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,yFAAyF;AACzF,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC,iEAAiE;AACjE,eAAO,MAAM,aAAa,MAAM,CAAC"}

package/dist/constants.js

@@ -1,7 +1,7 @@
-/** Separator used in "this", dim, and condition strings. @public */
+/** Separator used between parts of function-call and condition strings (e.g. `"key::value"`). */
 export const FN_SEPARATOR = '::';
-/** Prefix for data-context reference (entire state). @public */
+/** Prefix token that identifies a `(this)` data reference in inline-lang expressions. */
 export const DATA_THIS = '(this)';
-/** Separator for object paths (e.g. user.name). @public */
+/** Separator used when splitting dot-notation property paths. */
 export const DOT_SEPARATOR = '.';
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAEjC,gEAAgE;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAElC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAEjC,yFAAyF;AACzF,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAElC,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC"}

package/dist/dims.d.ts

@@ -1,13 +1,41 @@
-/** Dimension axis: width or height. @public */
+/** The canonical dimension axis: either `'width'` or `'height'`. */
 export type DimType = 'width' | 'height';
-/** Parsed dimension: [axis, multiplier 0..1]. @public */
+/**
+ * A parsed dimension tuple: `[axis, fraction]`.
+ *
+ * `fraction` is a value in the range `[0, 1]` representing the percentage of
+ * the parent container's corresponding axis, or `1` when no percentage is
+ * specified.
+ */
 export type Dims = [DimType, number];
-/** Allowed dimension string keys. @public */
+/**
+ * The string tokens recognised as dimension axis shorthands in inline-lang
+ * expressions (`'w'` and `'h'` are short forms; `'width'`/`'height'` are the
+ * long forms).
+ */
 export type DimsString = 'w' | 'h' | 'width' | 'height';
 /**
- * Parses a dimension string like `"w::50"` or `"height::100"` into [type, 0..1].
- * @param dim - Quoted string e.g. `"w::50"` (50% width), `"height"` (100% height)
- * @returns Tuple [DimType, number] or null if format is invalid
+ * Parses a dimension string into a `Dims` tuple.
+ *
+ * Dimension strings follow the pattern `<axis>[::percentage]`, where `axis` is
+ * one of `w`, `h`, `width`, or `height`, and the optional `percentage` suffix
+ * (separated by `::`) is an integer representing a percentage (e.g. `"w::50"`
+ * yields `['width', 0.5]`). When no percentage is provided the fraction
+ * defaults to `1`.
+ *
+ * Returns `null` for any string that does not match the expected pattern.
+ *
+ * @param dim - The dimension string to parse (e.g. `"w"`, `"height::75"`).
+ * @returns A `[DimType, fraction]` tuple, or `null` if the string is invalid.
+ *
+ * @example
+ * ```ts
+ * parseDims('w');        // ['width', 1]
+ * parseDims('h::50');    // ['height', 0.5]
+ * parseDims('width::100'); // ['width', 1]
+ * parseDims('invalid'); // null
+ * ```
+ *
  * @public
  */
 export declare const parseDims: (dim: string) => Dims | null;

package/dist/dims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dims.d.ts","sourceRoot":"","sources":["../src/dims.ts"],"names":[],"mappings":"AAIA,+CAA+C;AAC/C,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzC,yDAAyD;AACzD,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAErC,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,CAAC;AASxD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,IAAI,GAAG,IAS9C,CAAC"}
+{"version":3,"file":"dims.d.ts","sourceRoot":"","sources":["../src/dims.ts"],"names":[],"mappings":"AAIA,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAErC;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,CAAC;AASxD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,IAAI,GAAG,IAS9C,CAAC"}

package/dist/dims.js

@@ -7,9 +7,27 @@ const mapDimsType = {
     height: 'height',
 };
 /**
- * Parses a dimension string like `"w::50"` or `"height::100"` into [type, 0..1].
- * @param dim - Quoted string e.g. `"w::50"` (50% width), `"height"` (100% height)
- * @returns Tuple [DimType, number] or null if format is invalid
+ * Parses a dimension string into a `Dims` tuple.
+ *
+ * Dimension strings follow the pattern `<axis>[::percentage]`, where `axis` is
+ * one of `w`, `h`, `width`, or `height`, and the optional `percentage` suffix
+ * (separated by `::`) is an integer representing a percentage (e.g. `"w::50"`
+ * yields `['width', 0.5]`). When no percentage is provided the fraction
+ * defaults to `1`.
+ *
+ * Returns `null` for any string that does not match the expected pattern.
+ *
+ * @param dim - The dimension string to parse (e.g. `"w"`, `"height::75"`).
+ * @returns A `[DimType, fraction]` tuple, or `null` if the string is invalid.
+ *
+ * @example
+ * ```ts
+ * parseDims('w');        // ['width', 1]
+ * parseDims('h::50');    // ['height', 0.5]
+ * parseDims('width::100'); // ['width', 1]
+ * parseDims('invalid'); // null
+ * ```
+ *
  * @public
  */
 export const parseDims = (dim) => {

package/dist/dims.js.map

@@ -1 +1 @@
-{"version":3,"file":"dims.js","sourceRoot":"","sources":["../src/dims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,uBAAuB,YAAY,SAAS,CAAC,CAAC;AAW3E,MAAM,WAAW,GAAG;IAClB,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,QAAQ;IACX,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAW,EAAe,EAAE;IACpD,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAE1C,OAAO,CAAC,WAAW,CAAC,IAAkB,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC"}
+{"version":3,"file":"dims.js","sourceRoot":"","sources":["../src/dims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,uBAAuB,YAAY,SAAS,CAAC,CAAC;AAqB3E,MAAM,WAAW,GAAG;IAClB,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,QAAQ;IACX,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAW,EAAe,EAAE;IACpD,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAE1C,OAAO,CAAC,WAAW,CAAC,IAAkB,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,3 @@
-/**
- * @packageDocumentation
- * @module @mapples/inlang
- *
- * Internal language utilities for the Mapples Open Kit: parsing and evaluation
- * of "this" references, dimension strings, and condition strings used across
- * data bindings, visibility conditions, and layout.
- */
 export * from './this';
 export * from './state';
 export * from './dims';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -1,11 +1,3 @@
-/**
- * @packageDocumentation
- * @module @mapples/inlang
- *
- * Internal language utilities for the Mapples Open Kit: parsing and evaluation
- * of "this" references, dimension strings, and condition strings used across
- * data bindings, visibility conditions, and layout.
- */
 export * from './this';
 export * from './state';
 export * from './dims';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}

package/dist/state/conditions.d.ts

@@ -1,8 +1,22 @@
 import { ConditionFunc, Conditions } from './types';
-/** Equality condition: (a, b) => a === b. @public */
+/** Strict-equality condition: returns `true` when `a === b`. */
 export declare const eq: ConditionFunc;
-/** Not-equals condition: (a, b) => a !== b. @public */
+/** Strict-inequality condition: returns `true` when `a !== b`. */
 export declare const notEq: ConditionFunc;
-/** Map from Conditions enum to evaluator functions. @public */
+/**
+ * Lookup map from each {@link Conditions} operator to its corresponding
+ * {@link ConditionFunc} implementation.
+ *
+ * Use this map to resolve a condition operator string to an executable function
+ * at runtime.
+ *
+ * @example
+ * ```ts
+ * const fn = conditionMap[Conditions.equals];
+ * fn('foo', 'foo'); // true
+ * ```
+ *
+ * @public
+ */
 export declare const conditionMap: Record<Conditions, ConditionFunc>;
 //# sourceMappingURL=conditions.d.ts.map

package/dist/state/conditions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/state/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,qDAAqD;AACrD,eAAO,MAAM,EAAE,EAAE,aAAiC,CAAC;AAEnD,uDAAuD;AACvD,eAAO,MAAM,KAAK,EAAE,aAAiC,CAAC;AAEtD,+DAA+D;AAC/D,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,CAG1D,CAAC"}
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/state/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,gEAAgE;AAChE,eAAO,MAAM,EAAE,EAAE,aAAiC,CAAC;AAEnD,kEAAkE;AAClE,eAAO,MAAM,KAAK,EAAE,aAAiC,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,CAG1D,CAAC"}

package/dist/state/conditions.js

@@ -1,9 +1,23 @@
 import { Conditions } from './types';
-/** Equality condition: (a, b) => a === b. @public */
+/** Strict-equality condition: returns `true` when `a === b`. */
 export const eq = (a, b) => a === b;
-/** Not-equals condition: (a, b) => a !== b. @public */
+/** Strict-inequality condition: returns `true` when `a !== b`. */
 export const notEq = (a, b) => a !== b;
-/** Map from Conditions enum to evaluator functions. @public */
+/**
+ * Lookup map from each {@link Conditions} operator to its corresponding
+ * {@link ConditionFunc} implementation.
+ *
+ * Use this map to resolve a condition operator string to an executable function
+ * at runtime.
+ *
+ * @example
+ * ```ts
+ * const fn = conditionMap[Conditions.equals];
+ * fn('foo', 'foo'); // true
+ * ```
+ *
+ * @public
+ */
 export const conditionMap = {
     [Conditions.equals]: eq,
     [Conditions.notEquals]: notEq,

package/dist/state/conditions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conditions.js","sourceRoot":"","sources":["../../src/state/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,qDAAqD;AACrD,MAAM,CAAC,MAAM,EAAE,GAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAEnD,uDAAuD;AACvD,MAAM,CAAC,MAAM,KAAK,GAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAsC;IAC7D,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE;IACvB,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,KAAK;CAC9B,CAAC"}
+{"version":3,"file":"conditions.js","sourceRoot":"","sources":["../../src/state/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,gEAAgE;AAChE,MAAM,CAAC,MAAM,EAAE,GAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAEnD,kEAAkE;AAClE,MAAM,CAAC,MAAM,KAAK,GAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAsC;IAC7D,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE;IACvB,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,KAAK;CAC9B,CAAC"}

package/dist/state/regexp.d.ts

@@ -1,7 +1,9 @@
 /**
- * Regex to split condition strings on `::` while respecting quoted segments.
- * Used so values like `"a::b"` are not split on the inner `::`.
- * @public
+ * Regular expression used to split a condition string on the `::` separator,
+ * ignoring any `::` sequences that appear inside double-quoted substrings.
+ *
+ * This lookahead-based pattern ensures that quoted values (e.g. `"foo::bar"`)
+ * are treated as atomic tokens rather than split mid-value.
  */
 export declare const ConditionStringRegExp: RegExp;
 //# sourceMappingURL=regexp.d.ts.map

package/dist/state/regexp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regexp.d.ts","sourceRoot":"","sources":["../../src/state/regexp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAkC,CAAC"}
+{"version":3,"file":"regexp.d.ts","sourceRoot":"","sources":["../../src/state/regexp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAkC,CAAC"}

package/dist/state/regexp.js

@@ -1,7 +1,9 @@
 /**
- * Regex to split condition strings on `::` while respecting quoted segments.
- * Used so values like `"a::b"` are not split on the inner `::`.
- * @public
+ * Regular expression used to split a condition string on the `::` separator,
+ * ignoring any `::` sequences that appear inside double-quoted substrings.
+ *
+ * This lookahead-based pattern ensures that quoted values (e.g. `"foo::bar"`)
+ * are treated as atomic tokens rather than split mid-value.
  */
 export const ConditionStringRegExp = /::(?=(?:[^"]*"[^"]*")*[^"]*$)/;
 //# sourceMappingURL=regexp.js.map

package/dist/state/regexp.js.map

@@ -1 +1 @@
-{"version":3,"file":"regexp.js","sourceRoot":"","sources":["../../src/state/regexp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,+BAA+B,CAAC"}
+{"version":3,"file":"regexp.js","sourceRoot":"","sources":["../../src/state/regexp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,+BAA+B,CAAC"}

package/dist/state/types.d.ts

@@ -59,10 +59,10 @@ export type ValueType = 'string' | 'number' | 'boolean' | 'dataProp';
  * the condition operator, the value to compare against, and the type of that value.
  *
  * @interface ParseConditionResult
- * @property {string} dataProp - The data property path to evaluate
- * @property {Conditions} condition - The condition operator to use
- * @property {string | boolean} valueProp - The value to compare against
- * @property {ValueType} valueType - The type of the value (string, number, boolean, or dataProp)
+ * @property dataProp - The data property path to evaluate
+ * @property condition - The condition operator to use
+ * @property valueProp - The value to compare against
+ * @property valueType - The type of the value (string, number, boolean, or dataProp)
  * @public
  */
 export interface ParseConditionResult {

package/dist/state/utils.d.ts

@@ -1,16 +1,39 @@
 import { BoolCondition, ParseConditionResult, SimpleCondition } from './types';
 /**
- * Joins values with FN_SEPARATOR to build a condition string.
- * @param values - Parts to join (e.g. dataProp, condition, value)
- * @returns Single string with `::` between parts
+ * Joins one or more string parts into a single `::` -separated condition
+ * string.
+ *
+ * @param values - The parts to join (e.g. a data-prop, condition operator, and
+ *   comparison value).
+ * @returns A `::` -delimited string (e.g. `"user.age::eq::18"`).
+ *
+ * @example
+ * ```ts
+ * toConditionString('user.age', 'eq', '18'); // 'user.age::eq::18'
+ * ```
+ *
  * @public
  */
 export declare const toConditionString: (...values: string[]) => string;
 /**
- * Splits a condition string into parts; valueType is defaulted to 'string'.
- * For full parsing (booleans, quoted types, dataProp) use parseCondition.
- * @param value - Raw condition string
- * @returns ParseConditionResult with valueType 'string'
+ * Parses a raw condition string into its component parts without type coercion
+ * of the value.
+ *
+ * Unlike {@link parseCondition}, this function does not attempt to convert the
+ * value to a boolean or detect quoted/typed literals — it returns the raw
+ * string fragments and always sets `valueType` to `'string'`. Prefer
+ * {@link parseCondition} when the full type-aware parsing is needed.
+ *
+ * @param value - The raw condition string to parse (e.g. `"user.age::eq::18"`).
+ * @returns A {@link ParseConditionResult} with `valueType` always set to
+ *   `'string'`.
+ *
+ * @example
+ * ```ts
+ * parseConditionString('user.age::eq::18');
+ * // { dataProp: 'user.age', condition: 'eq', valueProp: '18', valueType: 'string' }
+ * ```
+ *
  * @public
  */
 export declare const parseConditionString: (value: string) => ParseConditionResult;
@@ -103,9 +126,23 @@ export declare const toBool: (value: string | boolean) => boolean;
  */
 export declare const toNumber: (value: string | boolean) => number;
 /**
- * Splits a multi-key string by `;` and strips newlines. Used for data-prop keys that join multiple paths.
- * @param key - Optional string (e.g. "user.name;user.email; ")
- * @returns Array of segments, or undefined if key is undefined
+ * Strips newline characters from `key` and splits it on semicolons, returning
+ * an array of the resulting segments.
+ *
+ * Returns `undefined` when `key` is `undefined`.
+ *
+ * @param key - An optional semicolon-delimited string, possibly containing
+ *   newline characters.
+ * @returns An array of string segments, or `undefined` if `key` is not
+ *   provided.
+ *
+ * @example
+ * ```ts
+ * parseJoin('a;b;c');       // ['a', 'b', 'c']
+ * parseJoin('a;\nb');       // ['a', 'b']
+ * parseJoin(undefined);     // undefined
+ * ```
+ *
  * @public
  */
 export declare const parseJoin: (key?: string) => string[] | undefined;

package/dist/state/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/state/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EAEb,oBAAoB,EACpB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAWjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,QAAQ,MAAM,EAAE,WAEpD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,oBAWpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,eAAe,GAAG,aAAa,KACrC,oBAgCF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,OAAO,YAI7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,GAAG,OAAO,WAU/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,yBAErC,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/state/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EAEb,oBAAoB,EACpB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAWjB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,QAAQ,MAAM,EAAE,WAEpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,oBAWpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,eAAe,GAAG,aAAa,KACrC,oBAgCF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,OAAO,YAI7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,GAAG,OAAO,WAU/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,yBAErC,CAAC"}

package/dist/state/utils.js

@@ -1,4 +1,4 @@
-import { FN_SEPARATOR } from '@mapples/inlang';
+import { FN_SEPARATOR } from '../constants';
 import { ConditionStringRegExp } from './regexp';
 const mapTypes = {
     str: 'string',
@@ -9,19 +9,42 @@ const mapTypes = {
     boolean: 'boolean',
 };
 /**
- * Joins values with FN_SEPARATOR to build a condition string.
- * @param values - Parts to join (e.g. dataProp, condition, value)
- * @returns Single string with `::` between parts
+ * Joins one or more string parts into a single `::` -separated condition
+ * string.
+ *
+ * @param values - The parts to join (e.g. a data-prop, condition operator, and
+ *   comparison value).
+ * @returns A `::` -delimited string (e.g. `"user.age::eq::18"`).
+ *
+ * @example
+ * ```ts
+ * toConditionString('user.age', 'eq', '18'); // 'user.age::eq::18'
+ * ```
+ *
  * @public
  */
 export const toConditionString = (...values) => {
     return values.join(FN_SEPARATOR);
 };
 /**
- * Splits a condition string into parts; valueType is defaulted to 'string'.
- * For full parsing (booleans, quoted types, dataProp) use parseCondition.
- * @param value - Raw condition string
- * @returns ParseConditionResult with valueType 'string'
+ * Parses a raw condition string into its component parts without type coercion
+ * of the value.
+ *
+ * Unlike {@link parseCondition}, this function does not attempt to convert the
+ * value to a boolean or detect quoted/typed literals — it returns the raw
+ * string fragments and always sets `valueType` to `'string'`. Prefer
+ * {@link parseCondition} when the full type-aware parsing is needed.
+ *
+ * @param value - The raw condition string to parse (e.g. `"user.age::eq::18"`).
+ * @returns A {@link ParseConditionResult} with `valueType` always set to
+ *   `'string'`.
+ *
+ * @example
+ * ```ts
+ * parseConditionString('user.age::eq::18');
+ * // { dataProp: 'user.age', condition: 'eq', valueProp: '18', valueType: 'string' }
+ * ```
+ *
  * @public
  */
 export const parseConditionString = (value) => {
@@ -166,9 +189,23 @@ export const toNumber = (value) => {
     return numValue;
 };
 /**
- * Splits a multi-key string by `;` and strips newlines. Used for data-prop keys that join multiple paths.
- * @param key - Optional string (e.g. "user.name;user.email; ")
- * @returns Array of segments, or undefined if key is undefined
+ * Strips newline characters from `key` and splits it on semicolons, returning
+ * an array of the resulting segments.
+ *
+ * Returns `undefined` when `key` is `undefined`.
+ *
+ * @param key - An optional semicolon-delimited string, possibly containing
+ *   newline characters.
+ * @returns An array of string segments, or `undefined` if `key` is not
+ *   provided.
+ *
+ * @example
+ * ```ts
+ * parseJoin('a;b;c');       // ['a', 'b', 'c']
+ * parseJoin('a;\nb');       // ['a', 'b']
+ * parseJoin(undefined);     // undefined
+ * ```
+ *
  * @public
  */
 export const parseJoin = (key) => {

package/dist/state/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/state/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/state/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AASjD,MAAM,QAAQ,GAAG;IACf,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,QAAQ;IACb,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;CACV,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,MAAgB,EAAE,EAAE;IACvD,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACnC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAa,EAAwB,EAAE;IAC1E,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,KAAK;SAC3C,IAAI,EAAE;SACN,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAEhC,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,SAAuB;QAClC,SAAS,EAAE,SAAS;QACpB,SAAS,EAAE,QAAQ;KACpB,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAsC,EAChB,EAAE;IACxB,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,KAAK;SAC3C,IAAI,EAAE;SACN,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAEhC,IAAI,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,OAAO;QAC/C,OAAO;YACL,QAAQ;YACR,SAAS,EAAE,SAAuB;YAClC,SAAS,EAAE,SAAS,KAAK,MAAM;YAC/B,SAAS,EAAE,SAAS;SACrB,CAAC;IAEJ,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAEtD,OAAO;YACL,QAAQ;YACR,SAAS,EAAE,SAAuB;YAClC,SAAS,EAAE,KAAK;YAChB,SAAS,EACP,QAAQ,CAAC,IAA6B,CAAC,IAAK,QAAsB;SACrE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,SAAuB;QAClC,SAAS;QACT,SAAS,EAAE,UAAU;KACtB,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAA4B,EAAE;IACtE,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,2DAA2D,CAAC,IAAI,CAAC,KAAK,CAAC,CACxE,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAuB,EAAE,EAAE;IAChD,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAE7C,OAAO,KAAK,KAAK,MAAM,CAAC;AAC1B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAuB,EAAE,EAAE;IAClD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAE/B,IAAI,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,CAAC;IAE9B,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAE,EAAE;IACxC,OAAO,GAAG,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC,CAAC"}

package/dist/this.d.ts

@@ -1,33 +1,78 @@
 /**
- * Tuple for parsed action/context "this" reference: `['this', optionalIndex]`.
- * @public
+ * Parsed representation of a `this` reference in an inline-lang expression.
+ *
+ * The first element is always `'this'`. The optional second element is a
+ * numeric index string when the reference targets a specific iteration item
+ * (e.g. `"this::0"` → `['this', '0']`).
  */
 export type This = ['this', string?];
 /**
- * Returns whether the string matches an action "this" reference: `"this"` or `"this::n"`.
- * @param value - String to test (e.g. from config)
- * @returns True if the value is a quoted "this" or "this::n" reference
+ * Returns `true` when `value` is a quoted `this` reference string.
+ *
+ * Matches the literal value `"this"` as well as indexed variants such as
+ * `"this::0"`.
+ *
+ * @param value - The string to test.
+ * @returns `true` if `value` is a `this` reference, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isThis('"this"');    // true
+ * isThis('"this::0"'); // true
+ * isThis('other');     // false
+ * ```
+ *
  * @public
  */
 export declare const isThis: (value?: string) => boolean;
 /**
- * Returns whether the string is a data-context reference starting with `(this)`.
- * @param value - String to test
- * @returns True if the value starts with DATA_THIS
+ * Returns `true` when `value` begins with the `(this)` data-reference prefix.
+ *
+ * @param value - The string to test.
+ * @returns `true` if `value` is a `(this)` data reference, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isDataThis('(this).name'); // true
+ * isDataThis('other');       // false
+ * ```
+ *
  * @public
  */
 export declare const isDataThis: (value?: string) => boolean | undefined;
 /**
- * Strips the `(this)` prefix and splits the rest by dot into path segments.
- * @param value - Full data-this string (e.g. `(this).user.name`)
- * @returns Array of path segments
+ * Strips the `(this)` prefix from a data-reference string and splits the
+ * remaining dot-notation path into an array of property segments.
+ *
+ * @param value - A `(this)`-prefixed data-reference string (e.g. `"(this).user.name"`).
+ * @returns An array of path segments after the `(this)` prefix (e.g. `['', 'user', 'name']`).
+ *
+ * @example
+ * ```ts
+ * parseDataThis('(this).user.name'); // ['', 'user', 'name']
+ * parseDataThis('(this)');           // ['']
+ * ```
+ *
  * @public
  */
 export declare const parseDataThis: (value: string) => string[];
 /**
- * Parses a quoted "this" or "this::n" string into a This tuple.
- * @param value - Quoted string (e.g. `"this"` or `"this::2"`)
- * @returns `['this']` or `['this', n]`; if value is falsy returns `['this']`
+ * Parses a quoted `this` reference string into a `This` tuple.
+ *
+ * Strips the surrounding quotes and splits on `::` to separate the `'this'`
+ * keyword from an optional index. When `value` is `undefined` or empty,
+ * returns the bare `['this']` tuple.
+ *
+ * @param value - An optional quoted `this` reference string (e.g. `'"this::0"'`).
+ * @returns A `This` tuple representing the reference.
+ *
+ * @example
+ * ```ts
+ * parseThis('"this"');    // ['this']
+ * parseThis('"this::0"'); // ['this', '0']
+ * parseThis(undefined);   // ['this']
+ * ```
+ *
  * @public
  */
 export declare const parseThis: (value?: string) => This;

package/dist/this.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"this.d.ts","sourceRoot":"","sources":["../src/this.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,MAAM,YAEpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,wBAExC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,aAE1C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,KAAG,IAE1C,CAAC"}
+{"version":3,"file":"this.d.ts","sourceRoot":"","sources":["../src/this.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,MAAM,YAEpC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,wBAExC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,aAE1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,KAAG,IAE1C,CAAC"}

package/dist/this.js

@@ -1,36 +1,78 @@
 import { DATA_THIS, DOT_SEPARATOR, FN_SEPARATOR } from './constants';
 const actionThisRegExp = new RegExp(`^"this(${FN_SEPARATOR}\\d+)?"$`);
 /**
- * Returns whether the string matches an action "this" reference: `"this"` or `"this::n"`.
- * @param value - String to test (e.g. from config)
- * @returns True if the value is a quoted "this" or "this::n" reference
+ * Returns `true` when `value` is a quoted `this` reference string.
+ *
+ * Matches the literal value `"this"` as well as indexed variants such as
+ * `"this::0"`.
+ *
+ * @param value - The string to test.
+ * @returns `true` if `value` is a `this` reference, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isThis('"this"');    // true
+ * isThis('"this::0"'); // true
+ * isThis('other');     // false
+ * ```
+ *
  * @public
  */
 export const isThis = (value) => {
     return actionThisRegExp.test(value || '');
 };
 /**
- * Returns whether the string is a data-context reference starting with `(this)`.
- * @param value - String to test
- * @returns True if the value starts with DATA_THIS
+ * Returns `true` when `value` begins with the `(this)` data-reference prefix.
+ *
+ * @param value - The string to test.
+ * @returns `true` if `value` is a `(this)` data reference, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isDataThis('(this).name'); // true
+ * isDataThis('other');       // false
+ * ```
+ *
  * @public
  */
 export const isDataThis = (value) => {
     return value?.startsWith(DATA_THIS);
 };
 /**
- * Strips the `(this)` prefix and splits the rest by dot into path segments.
- * @param value - Full data-this string (e.g. `(this).user.name`)
- * @returns Array of path segments
+ * Strips the `(this)` prefix from a data-reference string and splits the
+ * remaining dot-notation path into an array of property segments.
+ *
+ * @param value - A `(this)`-prefixed data-reference string (e.g. `"(this).user.name"`).
+ * @returns An array of path segments after the `(this)` prefix (e.g. `['', 'user', 'name']`).
+ *
+ * @example
+ * ```ts
+ * parseDataThis('(this).user.name'); // ['', 'user', 'name']
+ * parseDataThis('(this)');           // ['']
+ * ```
+ *
  * @public
  */
 export const parseDataThis = (value) => {
     return value.replace(DATA_THIS, '').split(DOT_SEPARATOR);
 };
 /**
- * Parses a quoted "this" or "this::n" string into a This tuple.
- * @param value - Quoted string (e.g. `"this"` or `"this::2"`)
- * @returns `['this']` or `['this', n]`; if value is falsy returns `['this']`
+ * Parses a quoted `this` reference string into a `This` tuple.
+ *
+ * Strips the surrounding quotes and splits on `::` to separate the `'this'`
+ * keyword from an optional index. When `value` is `undefined` or empty,
+ * returns the bare `['this']` tuple.
+ *
+ * @param value - An optional quoted `this` reference string (e.g. `'"this::0"'`).
+ * @returns A `This` tuple representing the reference.
+ *
+ * @example
+ * ```ts
+ * parseThis('"this"');    // ['this']
+ * parseThis('"this::0"'); // ['this', '0']
+ * parseThis(undefined);   // ['this']
+ * ```
+ *
  * @public
  */
 export const parseThis = (value) => {

package/dist/this.js.map

@@ -1 +1 @@
-{"version":3,"file":"this.js","sourceRoot":"","sources":["../src/this.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,UAAU,YAAY,UAAU,CAAC,CAAC;AAQtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAc,EAAE,EAAE;IACvC,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAE,EAAE;IAC3C,OAAO,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,EAAE;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;AAC3D,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAQ,EAAE;IAChD,OAAO,KAAK,CAAC,CAAC,CAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,CAAC,CAAC"}
+{"version":3,"file":"this.js","sourceRoot":"","sources":["../src/this.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,UAAU,YAAY,UAAU,CAAC,CAAC;AAWtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAc,EAAE,EAAE;IACvC,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAE,EAAE;IAC3C,OAAO,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,EAAE;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;AAC3D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAQ,EAAE;IAChD,OAAO,KAAK,CAAC,CAAC,CAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapples/inlang",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {