@entropicwarrior/sdoc 0.2.12 → 0.2.13

package/docs/reference/sdoc-authoring.sdoc

@@ -275,6 +275,66 @@ Content of Section B.
             }
             ```
 
+            # Column Directives @column-directives
+            {
+                An optional directive row after the header controls per-column alignment and number formatting. It is consumed by the parser and not rendered as data.
+
+                # Column Alignment
+                {
+                    Use \`<\` (left), \`>\` (right), or \`=\` (center):
+
+                    ```
+                    {[table]
+                        Programme | Amount | Status
+                        < | > | =
+                        Alpha | $1,000,000 | Active
+                        Beta | $2,500,000 | Pending
+                    }
+                    ```
+
+                    If absent, all columns default to left. Empty cells in the directive row keep the default. Alignment applies to both header and data cells.
+
+                    For headerless tables, the directive row is the first row — it is consumed but no header is rendered:
+
+                    ```
+                    {[table headerless]
+                        < | >
+                        Alice | 100
+                        Bob | 200
+                    }
+                    ```
+                }
+
+                # Column Formatting
+                {
+                    A format token in the directive row formats numeric cells and formula results in that column. Text cells (like bold labels) pass through unchanged. The format is display-only — formulas always use raw numeric values.
+
+                    {[.]
+                        - \`$\` — currency, no decimals: \`$1,000,000\`
+                        - \`$.N\` — currency with N decimals: \`$.2\` → \`$1,234.50\`
+                        - \`,\` — thousands separator: \`1,000,000\`
+                        - \`,.N\` — thousands with N decimals: \`,.2\` → \`1,234,567.89\`
+                        - \`.N\` — fixed N decimals: \`.2\` → \`3.14\`
+                        - \`%\` — percentage (value × 100): \`0.452\` → \`45.2%\`
+                        - \`%.N\` — percentage with N decimals: \`%.1\` → \`45.7%\`
+                    }
+
+                    Alignment and format combine in a single directive cell:
+
+                    ```
+                    {[table]
+                        Item | Amount
+                        < | > $
+                        Widget | 1000000
+                        Gadget | 2500000
+                        **Total** | =SUM(B1:B2)
+                    }
+                    ```
+
+                    The \`Amount\` column is right-aligned and formatted as currency. The formula result and data cells all display as \`$1,000,000\` style. The \`**Total**\` label renders as bold text.
+                }
+            }
+
             # Table Formulas @table-formulas
             {
                 Cells starting with \`=\` are evaluated as formulas. Hover a computed cell in preview to see the original formula.
@@ -282,9 +342,10 @@ Content of Section B.
                 ```
                 {[table]
                     Investor | Shares | Ownership
-                    Seed Fund | 500,000 | 25%
-                    Founder A | 1,000,000 | 50%
-                    Founder B | 500,000 | 25%
+                    < | > , | > %
+                    Seed Fund | 500000 | 0.25
+                    Founder A | 1000000 | 0.50
+                    Founder B | 500000 | 0.25
                     **Total** | =SUM(B1:B3) | =SUM(C1:C3)
                 }
                 ```
@@ -301,6 +362,8 @@ Content of Section B.
                 }
 
                 Errors display in red italic: \`#DIV/0!\` (division by zero), \`#VALUE!\` (bad reference), \`#REF!\` (invalid syntax), \`#NAME!\` (unknown function), \`#CIRCULAR!\` (circular dependency).
+
+                **Tip:** Use numeric values with a column format directive (e.g. \`> $\`) instead of pre-formatted strings like \`$1,000,000\`. Formatted strings are text — formulas cannot reference them.
             }
         }
 

package/lexica/specification.sdoc

@@ -380,6 +380,69 @@ Content of Section B.
                 ```
             }
 
+            # Column Directives @column-directives
+            {
+                An optional directive row immediately after the header row (or as the first row in a headerless table) controls per-column alignment and number formatting. The directive row is consumed by the parser and never rendered as data.
+
+                # Column Alignment @column-alignment
+                {
+                    Alignment characters in the directive row set the text-align for all cells in that column, including the header:
+
+                    {[.]
+                        - `<` — left (default)
+                        - `>` — right (most useful for numbers and currency)
+                        - `=` — center
+                    }
+
+                    ```
+{[table]
+    Programme | Amount | Status
+    < | > | =
+    Alpha | $1,000,000 | Active
+    Beta | $2,500,000 | Pending
+}
+                    ```
+
+                    If the directive row is absent, all columns default to left alignment. Empty cells in the directive row inherit the default (left).
+                }
+
+                # Column Formatting @column-formatting
+                {
+                    A format token in the directive row causes numeric cells and formula results in that column to be formatted for display. Text cells are unaffected. The format is display-only — formulas always operate on raw numeric values.
+
+                    {[.]
+                        - `$` — currency, no decimals: `1000000` → `$1,000,000`
+                        - `$.N` — currency with N decimals: `$.2` → `$1,234.50`
+                        - `,` — thousands separator, no decimals: `1000000` → `1,000,000`
+                        - `,.N` — thousands with N decimals: `,.2` → `1,234,567.89`
+                        - `.N` — fixed N decimals: `.2` → `3.14`
+                        - `%` — percentage (value × 100, auto decimals): `0.452` → `45.2%`
+                        - `%.N` — percentage with N decimals: `%.1` → `45.7%`
+                    }
+
+                    A directive cell may combine alignment and format, separated by whitespace:
+
+                    ```
+{[table]
+    Item | Amount
+    < | > $
+    Widget | 1000000
+    Gadget | 2500000
+    **Total** | =SUM(B1:B2)
+}
+                    ```
+
+                    All numeric values and formula results in the `Amount` column display as currency (`$3,500,000`). The `**Total**` label renders normally as bold text.
+                }
+
+                # Directive Row Detection @directive-detection
+                {
+                    A row is identified as a directive row when every non-empty cell contains only an alignment character (`<`, `>`, `=`), a format token, or both. It must be the first row after the header (or the first row in a headerless table), and at least one cell must contain a directive.
+
+                    For headerless tables, the directive row functions as a virtual header — it is consumed for its directives but no `<thead>` is rendered.
+                }
+            }
+
             # Table Formulas @table-formulas
             {
                 Table cells whose text begins with `=` (but not `==`) are evaluated as formulas. The result replaces the cell text in rendered output; the original formula is preserved as a tooltip.
@@ -1083,7 +1146,14 @@ Content of Section A.
                       | "left" | "center" | "right" ;
         percentage    = digit { digit } [ "." digit { digit } ] "%" ;
         pixels        = digit { digit } "px" ;
-        table_body    = table_row { table_row } ;
+        table_body    = [ directive_row ] table_row { table_row } ;
+        directive_row = directive_cell { "|" directive_cell } ;
+        directive_cell = [ align_char ] [ ws format_spec ] ;
+        align_char    = "<" | ">" | "=" ;
+        format_spec   = "$" [ "." digits ]
+                      | "," [ "." digits ]
+                      | "." digits
+                      | "%" [ "." digits ] ;
         table_row     = cell { "|" cell } ;
         citations_scope = citations_open ws? citations_body "}" ;
         citations_open  = "{[citations]" ;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -63,6 +63,105 @@ function parseTableOptions(text) {
   return options;
 }
 
+// ── Column directive row (alignment + format) ──────────────────────────
+
+function isDirectiveRow(cells) {
+  if (cells.length === 0) return false;
+  const pattern = /^([<>=])?\s*(\$(?:\.\d+)?|,(?:\.\d+)?|\.\d+|%(?:\.\d+)?)?$/;
+  let hasDirective = false;
+  for (const cell of cells) {
+    const trimmed = cell.trim();
+    if (trimmed === "") continue;
+    if (!pattern.test(trimmed)) return false;
+    hasDirective = true;
+  }
+  return hasDirective;
+}
+
+function parseFormatSpec(spec) {
+  if (!spec) return null;
+  if (spec.startsWith("$")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : 0;
+    return { prefix: "$", thousands: true, decimals, percent: false };
+  }
+  if (spec.startsWith("%")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : -1;
+    return { prefix: "", thousands: false, decimals, percent: true };
+  }
+  if (spec.startsWith(",")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : 0;
+    return { prefix: "", thousands: true, decimals, percent: false };
+  }
+  if (spec.startsWith(".")) {
+    const decimals = parseInt(spec.slice(1), 10);
+    return { prefix: "", thousands: false, decimals, percent: false };
+  }
+  return null;
+}
+
+function parseDirectiveRow(cells) {
+  const align = [];
+  const format = [];
+  let hasAlign = false;
+  let hasFormat = false;
+  const fmtPattern = /(\$(?:\.\d+)?|,(?:\.\d+)?|\.\d+|%(?:\.\d+)?)$/;
+
+  for (const cell of cells) {
+    const trimmed = cell.trim();
+    const alignMatch = trimmed.match(/^([<>=])/);
+    const fmtMatch = trimmed.match(fmtPattern);
+
+    let a = null;
+    if (alignMatch) {
+      a = alignMatch[1] === "<" ? "left" : alignMatch[1] === ">" ? "right" : "center";
+      hasAlign = true;
+    }
+    align.push(a);
+
+    let f = null;
+    if (fmtMatch) {
+      f = parseFormatSpec(fmtMatch[1]);
+      hasFormat = true;
+    }
+    format.push(f);
+  }
+
+  return {
+    align: hasAlign ? align : null,
+    format: hasFormat ? format : null,
+  };
+}
+
+function formatNumber(value, spec) {
+  if (spec.percent) {
+    const pct = value * 100;
+    if (spec.decimals < 0) {
+      return (Number.isInteger(pct) ? pct.toString() : pct.toFixed(2).replace(/\.?0+$/, "")) + "%";
+    }
+    return pct.toFixed(spec.decimals) + "%";
+  }
+
+  const negative = value < 0;
+  const absVal = Math.abs(value);
+  let result;
+
+  if (spec.decimals > 0) {
+    result = absVal.toFixed(spec.decimals);
+  } else {
+    result = Math.round(absVal).toString();
+  }
+
+  if (spec.thousands) {
+    const parts = result.split(".");
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    result = parts.join(".");
+  }
+
+  return (negative ? "-" : "") + spec.prefix + result;
+}
+
+// ── End column directive row ────────────────────────────────────────────
+
 class LineCursor {
   constructor(lines) {
     this.lines = lines;
@@ -835,18 +934,31 @@ function parseTableBody(cursor, tableStartLine, options) {
     cursor.next();
   }
 
+  // Detect column directive row (alignment / formatting)
+  // For headerless tables: check rows[0]; for normal tables: check rows[1] (after header)
+  const directiveIndex = options.headerless ? 0 : 1;
+  let columnAlign = null;
+  let columnFormat = null;
+  if (rows.length > directiveIndex && isDirectiveRow(rows[directiveIndex])) {
+    const directives = parseDirectiveRow(rows[directiveIndex]);
+    columnAlign = directives.align;
+    columnFormat = directives.format;
+    rows.splice(directiveIndex, 1);
+  }
+
   const hasOptions = options.borderless || options.headerless || options.width || options.align;
 
+  let tableNode;
   if (options.headerless) {
-    const tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
-    if (hasOptions) tableNode.options = options;
-    return tableNode;
+    tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
+  } else {
+    const headers = rows.length > 0 ? rows[0] : [];
+    const body = rows.slice(1);
+    tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
   }
-
-  const headers = rows.length > 0 ? rows[0] : [];
-  const body = rows.slice(1);
-  const tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
   if (hasOptions) tableNode.options = options;
+  if (columnAlign) tableNode.columnAlign = columnAlign;
+  if (columnFormat) tableNode.columnFormat = columnFormat;
   return tableNode;
 }
 
@@ -2122,15 +2234,23 @@ function formatFormulaResult(cell) {
 function renderTable(table) {
   const dl = dataLineAttrs(table);
   const opts = table.options || {};
+  const colAlign = table.columnAlign || [];
+  const colFormat = table.columnFormat || [];
   const classes = ["sdoc-table"];
   if (opts.borderless) classes.push("sdoc-table-borderless");
   if (opts.headerless) classes.push("sdoc-table-headerless");
   const classAttr = classes.join(" ");
 
+  function cellStyle(colIndex) {
+    const align = colAlign[colIndex];
+    if (!align || align === "left") return "";
+    return ` style="text-align:${align}"`;
+  }
+
   let thead = "";
   if (table.headers.length > 0) {
     const headerCells = table.headers
-      .map((cell) => `<th class="sdoc-table-th">${renderInline(cell)}</th>`)
+      .map((cell, c) => `<th class="sdoc-table-th"${cellStyle(c)}>${renderInline(cell)}</th>`)
       .join("");
     thead = `<thead class="sdoc-table-head"><tr>${headerCells}</tr></thead>`;
   }
@@ -2142,16 +2262,33 @@ function renderTable(table) {
     .map((row, r) => {
       const cells = row
         .map((cell, c) => {
+          const style = cellStyle(c);
+          const fmt = colFormat[c] || null;
+
           if (isFormulaCell(cell)) {
             const result = grid[r][c];
-            const display = escapeHtml(formatFormulaResult(result));
+            let display;
+            if (!result.error && fmt) {
+              display = escapeHtml(formatNumber(result.value, fmt));
+            } else {
+              display = escapeHtml(formatFormulaResult(result));
+            }
             const formula = escapeAttr(cell.trim());
             if (result.error) {
-              return `<td class="sdoc-table-td sdoc-formula-error" title="${formula}">${display}</td>`;
+              return `<td class="sdoc-table-td sdoc-formula-error"${style} title="${formula}">${display}</td>`;
             }
-            return `<td class="sdoc-table-td sdoc-formula-cell" title="${formula}">${display}</td>`;
+            return `<td class="sdoc-table-td sdoc-formula-cell"${style} title="${formula}">${display}</td>`;
           }
-          return `<td class="sdoc-table-td">${renderInline(cell)}</td>`;
+
+          // Apply column format to numeric data cells
+          if (fmt) {
+            const parsed = parseCellValue(cell);
+            if (!isNaN(parsed.value)) {
+              return `<td class="sdoc-table-td"${style}>${escapeHtml(formatNumber(parsed.value, fmt))}</td>`;
+            }
+          }
+
+          return `<td class="sdoc-table-td"${style}>${renderInline(cell)}</td>`;
         })
         .join("");
       return `<tr>${cells}</tr>`;