docs: update to match new mathflow api

this commit adds a drafted documentation for `refactor/code` branch - [refactor/code](mathflowjs/mathflow@247acc8)

Author: henryhale

docs/.vitepress/config.ts

@@ -36,7 +36,6 @@ export default defineConfig({
                 items: [
                     { text: 'Introduction', link: '/guide/' },
                     { text: 'Getting Started', link: '/guide/getting-started' },
-                    { text: 'Configuration', link: '/guide/config' }
                 ]
             },
             {
@@ -49,15 +48,19 @@ export default defineConfig({
                 ]
             },
             {
-                text: 'Examples',
+                text: 'Reference',
                 items: [
-                    { text: 'Scripts', link: '/guide/scripts' },
-                    { text: 'Programs', link: '/guide/programs' }
+                    { text: 'Context API', link: '/api/' },
+                    { text: 'Procedural API', link: '/api/procedural' },
+                    { text: 'Error Handling', link: '/api/errors' },
+                    { text: 'Rendering', link: '/api/rendering' },
                 ]
             },
             {
-                text: 'API Reference',
-                link: '/api/'
+                text: 'Examples',
+                items: [
+                    { text: 'Samples', link: '/examples/' }
+                ]
             }
         ],
 
@@ -68,17 +71,17 @@ export default defineConfig({
         editLink: {
             text: 'Edit this page on GitHub',
             pattern:
-                'https://github.com/mathflowjs/mathflow/edit/master/:path'
+                'https://github.com/mathflowjs/mathflowjs.github.io/edit/master/docs/:path'
         },
 
         footer: {
             message:
-                'Released under the <a href="https://github.com/mathflowjs/mathflow/blob/master/LICENSE.md">MIT License</a>.',
+                'Released under the <a href="https://github.com/mathflowjs/mathflow/blob/master/LICENSE.txt">MIT License</a>.',
             copyright:
-                'Copyright &copy; 2024, <a href="https://github.com/henryhale">Henry Hale</a> - 2024-present MathFlow.'
+                'Copyright &copy; 2024-present, <a href="https://github.com/henryhale">Henry Hale</a>.'
         }
     },
     markdown: {
-        lineNumbers: true
+        lineNumbers: false
     }
 });

docs/.vitepress/theme/assets/styles.css

@@ -1,7 +1,7 @@
 :root {
     --vp-c-brand-1: #4169e1;
     --vp-c-brand-2: #747bff;
-    --vp-home-hero-image-background-image: linear-gradient(180deg, var(--vp-home-hero-name-color) 50%,#27332a 50%);
+    --vp-home-hero-image-background-image: linear-gradient(180deg, var(--vp-home-hero-name-color), var(--vp-home-hero-name-color));
     --vp-home-hero-image-filter: blur(40px);
 }
 

docs/api/errors.md

@@ -0,0 +1,18 @@
+# Error Handling
+
+## Overview
+
+MathFlow throws errors for invalid syntax or unsupported operations. Use _try/catch_ to handle them:
+
+```ts
+import { createContext } from 'mathflow';
+
+const ctx = createContext();
+
+try {
+  ctx.solve('invalid = ');
+} catch (err) {
+  console.error('MathFlow error:', err);
+}
+```
+

docs/api/index.md

@@ -1,79 +1,203 @@
-# API Reference
+# Context API
 
-## evaluate()
+MathFlow configuration is managed through the properties of a context. 
 
-Evaluate a source code written using MathFlow syntax
+Use the `ContextAPI` for most tasks. This provides a simple interface for solving, rendering, and managing variables/functions/constants.
 
-- **Type**
+## Creating a context
 
-    ```ts
-    type Scope = {
-        variables: Record<string, number>;
-    };
+- **Type**: `function createContext(options?: Partial<ContextOptions>): ContextAPI`
 
-    type Result = {
-        value: number;
-        scope: Scope;
-        solution: string[];
-    };
+Use `createContext` to manage isolated or persistent variable scopes:
 
-    declare function evaluate(code: string): Result;
-    ```
+```ts
+import { createContext } from 'mathflow';
 
-- **Details**
+const ctx = createContext({
+    // ...
+})
+```
 
-    It takes one argument that must be a string containing MathFlow expressions.
+### preferences
+You can set preferences when creating a context, or update them at any time. 
 
-- **Example**
+```ts
+const ctx = createContext({
+    preferences: {
+        // key: value
+    }
+})
+```
 
-    Adding two numbers: `1` and `2`
+```ts
+type Preferences = {
+    angles: 'rad' | 'deg';
+    fractionDigits: number;
+    precision: number;
+};
+```
 
-    ```ts
-    import { evaluate } from 'mathflow';
+#### angles
 
-    const script = `
-    # declare variables
-    a = 1
-    b = 2
-    # compute sum
-    c = a + b
-    # return value
-    c
-    `;
+- **Type**: `rad` - radians | `deg` - degrees
+- **Default**: `rad`
 
-    const result = evaluate(script);
+Mode of angles - trignometric functions depend on `angles` to handle arguments and return values. 
 
-    console.log(result);
-    // Output: { value: 3, scope: { variables: { a: 1, b: 2, c: 3 } }, solution: ['3'] }
-    ```
+```ts
+const ctx = createContext({
+    preferences: {
+        angles: 'deg'
+    }
+})
 
-- **See also:** [Guide - Getting Started](../guide/getting-started.md) or [Guide - Syntax](../guide/basics.md) for details.
+// or
 
-## config
+ctx.preferences.angles = 'deg'
 
-Configure the behaviour of the compiler
+// example: sin(30) = 0.5 in degrees mode
+```
 
-- **Type**
+#### fractionDigits
 
-    ```ts
-    type Config = {
-        fractionDigits: number;
-    };
-    ```
+- **Type**: `number` 
+- **Default**: `15`
 
-- **Details**
-    
-    - `config.fractionDigits` sets the number of digits after the floating point.
-    
-- **Example**
-  
-    ```ts
-    import { config, evaluate } from 'mathflow';
+Number of digits after the decimal point. Must be in the range `0` - `20`, inclusive.
 
-    config.fractionDigits = 3;
+```ts
+const ctx = createContext({
+    preferences: {
+        fractionDigits: 10
+    }
+})
 
-    console.log(
-        evaluate(`1/6`).value
-    );
-    //Output: 0.167
-    ```
+// or
+
+ctx.preferences.fractionDigits = 'deg'
+```
+
+#### precision
+
+- **Type**: `number` 
+- **Default**: `15`
+
+Number of significant digits. Must be in the range 1 - 21, inclusive.
+
+```ts
+const ctx = createContext({
+    preferences: {
+        precision: 20
+    }
+})
+
+// or
+
+ctx.preferences.precision = 'deg'
+```
+
+### variables
+You can provide predefined variables to the context at its creation:
+
+- **Type**: `Record<string, number>`
+
+```ts
+const ctx = createContext({
+    variables: {
+        x: 1,
+    }
+})
+```
+
+For an existing context, use:
+
+- **Type**: `Map<string, number>`
+
+```ts
+ctx.variables.set('x', 1)
+```
+
+### constants
+
+Like [variables](#variables), the constants can be defined in a similar way:
+
+```ts
+const ctx = createContext({
+    constants: {
+        g: 9.81
+    }
+})
+
+// or
+
+ctx.constants.set('g', 9.81)
+```
+
+### functions
+
+Add custom functions to a context.
+
+- **Type**: `(...args: number[]) => number`
+
+```ts
+const ctx = createContext({
+    functions: {
+        double: (x) => 2 * x,
+    }
+})
+```
+
+For an existing context, use:
+
+- **Type**: `Map<string, number>`
+
+```ts
+ctx.functions.set('double', (x) => 2 * x)
+```
+
+## Solving expressions
+
+### solve
+
+Evaluate a single mathematical expression string
+
+- **Type**: `(code: string) => ({ value: number, solution: string[] })`
+
+```js
+ctx.solve('1 + 3 + 5')
+// { value: 9, solution: ['4 + 5', '9'] }
+```
+
+### solveBatch
+
+Evaluate multiple mathematical expressions at once
+
+- **Type**: `(code: string) => ({ value: number, solution: string[] }[])`
+
+```ts
+ctx.solveBatch(`x=2\ny=3x\nz=x+y`)
+// [ 
+//   { value: 2, solution: ['2'] },
+//   { value: 6, solution: ['3 * 2', '6'] },
+//   { value: 8, solution: ['2 + 6', '8'] },
+// ]
+```
+
+## Rendering expressions
+
+### renderAsHTML
+
+- **Type**: 
+- [default]
+- [description]
+- [example]
+- [see-also]
+
+### renderAsLaTeX
+
+
+- **Type**: 
+- [default]
+- [description]
+- [example]
+- [see-also]

docs/api/procedural.md

@@ -0,0 +1,27 @@
+# Procedural API
+
+For full control, use the lower-level API. This is useful for step-by-step evaluation, custom solution tracking, or building your own tools.
+
+## Overview
+
+
+### tokenize
+
+### parse
+
+### createSolutionStack
+
+### evaluate
+
+
+## Step-by-step Example
+```ts
+import { createContext, tokenize, parse, evaluate, createSolutionStack } from 'mathflow';
+const ctx = createContext({ variables: { x: 1 } });
+const solution = createSolutionStack();
+const tokens = tokenize(ctx, '1+2+x');
+const ast = parse(tokens);
+const value = evaluate(ctx, ast.body[0], solution);
+console.log(value); // 4
+console.log(solution.steps); // step-by-step solution
+```