brand-intent 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",

package/parser/compositionParser.ts

@@ -22,6 +22,26 @@ export interface ParsedImageRegion {
   colEnd?: number;    // 0-based column (undefined = full width)
 }
 
+/** Anchor keywords for illustration placement. */
+export type IllustrationAnchor =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'center-left' | 'center' | 'center-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+/** Parsed illustration placement from `illustration:` line. */
+export interface ParsedIllustration {
+  anchor: IllustrationAnchor;
+  fit: 'width' | 'height';
+  /** Scale as fraction 0–1 (e.g. 0.9 = 90% of canvas dimension). */
+  scale: number;
+}
+
+const ILLUSTRATION_ANCHORS = new Set<string>([
+  'top-left', 'top-center', 'top-right',
+  'center-left', 'center', 'center-right',
+  'bottom-left', 'bottom-center', 'bottom-right',
+]);
+
 export interface ParsedComposition {
   /** Programmatic ID (from `id:` line, or fallback from first `#` line). */
   id: string;
@@ -44,6 +64,8 @@ export interface ParsedComposition {
   sticky: ParsedStickyRegion[];
   /** Flow regions — content-driven flow areas. */
   flow: ParsedFlowRegion | null;
+  /** Illustration placement (grid mode only for now). */
+  illustration?: ParsedIllustration;
 }
 
 /** A sticky (repetition) region — composed elements that don't participate in flow. */
@@ -128,8 +150,6 @@ export interface ParsedDivider {
 
 // ── Constants ─────────────────────────────────────────────────────────────────
 
-/** Backward-compat map: band letters A-F → 0-based row indices */
-const LEGACY_BAND_MAP: Record<string, number> = { A: 0, B: 1, C: 2, D: 3, E: 4, F: 5 };
 const GRID_Y_KEYWORDS = new Set<string>(['top', 'center', 'bottom']);
 
 const VALID_SLOTS = new Set<string>(['primary', 'secondary', 'detail', 'meta', 'cta', 'label']);
@@ -181,6 +201,7 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
   const slots: ParsedSlot[] = [];
   const sticky: ParsedStickyRegion[] = [];
   let flow: ParsedFlowRegion | null = null;
+  let illustration: ParsedIllustration | undefined = undefined;
 
   /** Parse a fraction string like "2/3" → 0.667. */
   function parseFraction(s: string, ctx: string): number {
@@ -262,6 +283,23 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
       continue;
     }
 
+    // Illustration placement: "illustration: bottom-center fit-width 90%"
+    if (line.startsWith('illustration:')) {
+      const parts = line.slice(13).trim().split(/\s+/);
+      if (parts.length < 3) throw new Error(`${fileName}:${lineNum}: invalid illustration line — expected "illustration: <anchor> <fit-width|fit-height> <N%>"`);
+      const anchor = parts[0];
+      if (!ILLUSTRATION_ANCHORS.has(anchor)) throw new Error(`${fileName}:${lineNum}: invalid illustration anchor "${anchor}" (expected ${[...ILLUSTRATION_ANCHORS].join(', ')})`);
+      const fitStr = parts[1];
+      if (fitStr !== 'fit-width' && fitStr !== 'fit-height') throw new Error(`${fileName}:${lineNum}: invalid illustration fit "${fitStr}" (expected fit-width or fit-height)`);
+      const scaleStr = parts[2];
+      const scaleMatch = scaleStr.match(/^(\d+(?:\.\d+)?)%$/);
+      if (!scaleMatch) throw new Error(`${fileName}:${lineNum}: invalid illustration scale "${scaleStr}" (expected e.g. "90%")`);
+      const scale = parseFloat(scaleMatch[1]) / 100;
+      if (scale <= 0 || scale > 2) throw new Error(`${fileName}:${lineNum}: illustration scale out of range (expected 1%–200%)`);
+      illustration = { anchor: anchor as IllustrationAnchor, fit: fitStr === 'fit-width' ? 'width' : 'height', scale };
+      continue;
+    }
+
     // grid: is no longer used in layout files (format owns the grid). Silently skip.
     if (line.startsWith('grid:')) {
       console.warn(`${fileName}:${lineNum}: "grid:" in layout files is no longer needed — format defines the grid`);
@@ -292,16 +330,6 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
         logo = { row: parseInt(rowMatch[1], 10) - 1, col, size: (rowMatch[3] as 's' | 'm' | 'l') ?? undefined };
         continue;
       }
-      // Backward compat: "logo: band A [col] X"
-      const bandMatch = line.match(/^logo:\s+band\s+([A-F])\s+(?:col\s+)?(left|center|right)(?:\s+(s|m|l))?\s*$/);
-      if (bandMatch) {
-        const row = LEGACY_BAND_MAP[bandMatch[1]];
-        if (row === undefined) throw new Error(`${fileName}:${lineNum}: unknown band "${bandMatch[1]}"`);
-        console.warn(`${fileName}:${lineNum}: deprecated "band ${bandMatch[1]}" syntax — use "row ${row + 1}" instead`);
-        const col = resolveColKeyword(bandMatch[2], fileName, lineNum);
-        logo = { row, col, size: (bandMatch[3] as 's' | 'm' | 'l') ?? undefined };
-        continue;
-      }
       throw new Error(`${fileName}:${lineNum}: invalid logo line "${line}" (expected "logo: row N left|center|right" or "logo: top/center/bottom left|center|right")`);
     }
 
@@ -319,15 +347,6 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
         icon = { row: parseInt(rowMatch[1], 10) - 1, col, size: (rowMatch[3] as 's' | 'm' | 'l') ?? undefined };
         continue;
       }
-      const bandMatch = line.match(/^icon:\s+band\s+([A-F])\s+(?:col\s+)?(left|center|right)(?:\s+(s|m|l))?\s*$/);
-      if (bandMatch) {
-        const row = LEGACY_BAND_MAP[bandMatch[1]];
-        if (row === undefined) throw new Error(`${fileName}:${lineNum}: unknown band "${bandMatch[1]}"`);
-        console.warn(`${fileName}:${lineNum}: deprecated "band ${bandMatch[1]}" syntax — use "row ${row + 1}" instead`);
-        const col = resolveColKeyword(bandMatch[2], fileName, lineNum);
-        icon = { row, col, size: (bandMatch[3] as 's' | 'm' | 'l') ?? undefined };
-        continue;
-      }
       throw new Error(`${fileName}:${lineNum}: invalid icon line "${line}"`);
     }
 
@@ -511,25 +530,6 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
       continue;
     }
 
-    // Backward compat: "primary  band D  cols 1--4  left"
-    const bandSlotMatch = line.match(/^(\w+)\s+band\s+([A-F])\s+cols\s+(\S+)\s+(left|center|right)$/);
-    if (bandSlotMatch) {
-      const [, slotId, bandLetter, colRange, align] = bandSlotMatch;
-      if (!VALID_SLOTS.has(slotId)) throw new Error(`${fileName}:${lineNum}: unknown slot "${slotId}"`);
-      const row = LEGACY_BAND_MAP[bandLetter];
-      if (row === undefined) throw new Error(`${fileName}:${lineNum}: unknown band "${bandLetter}"`);
-      console.warn(`${fileName}:${lineNum}: deprecated "band ${bandLetter}" syntax — use "row ${row + 1}" instead`);
-      const cols = parseColRange(colRange, fileName, lineNum, 12);
-      slots.push({
-        id: slotId as SlotId,
-        row,
-        colStart: cols.start,
-        colEnd: cols.end,
-        textAlign: align as 'left' | 'center' | 'right',
-      });
-      continue;
-    }
-
     // Unknown line
     throw new Error(`${fileName}:${lineNum}: unexpected "${line}"`);
   }
@@ -552,5 +552,5 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
   // Validate required fields
   if (!image) image = 'full'; // default to full-bleed image
   if (!logo && !logoNone && !sticky.length) throw new Error(`${fileName}: missing "logo:" line (or use sticky: block)`);
-  return { id, name, description, mode, image, imageExplicit, logo, logoNone: logoNone || undefined, icon, slots, sticky, flow };
+  return { id, name, description, mode, image, imageExplicit, logo, logoNone: logoNone || undefined, icon, slots, sticky, flow, illustration };
 }

package/parser/formatParser.ts

@@ -29,7 +29,7 @@ export interface ParsedFormat {
   dpi?: number;
   bleedMm?: number;
   // Optional grid override — absent means auto portrait/landscape selection
-  grid?: { bands: number; cols: number };
+  grid?: { rows: number; cols: number };
   // Zones — always stored in px (mm values converted during parse)
   danger: ZoneInsets;
   gridCrop: ZoneInsets | null;
@@ -183,12 +183,12 @@ export function parseFormatFile(content: string, fileName: string): ParsedFormat
 
       case 'grid': {
         const parts = value.split(/\s+/);
-        if (parts.length !== 2) throw new Error(`${fileName}:${lineNum}: grid requires "bands cols", got "${value}"`);
-        const bands = parseInt(parts[0], 10);
+        if (parts.length !== 2) throw new Error(`${fileName}:${lineNum}: grid requires "rows cols", got "${value}"`);
+        const rows = parseInt(parts[0], 10);
         const cols  = parseInt(parts[1], 10);
-        if (isNaN(bands) || bands < 1 || isNaN(cols) || cols < 1)
-          throw new Error(`${fileName}:${lineNum}: grid bands and cols must be positive integers`);
-        grid = { bands, cols };
+        if (isNaN(rows) || rows < 1 || isNaN(cols) || cols < 1)
+          throw new Error(`${fileName}:${lineNum}: grid rows and cols must be positive integers`);
+        grid = { rows, cols };
         break;
       }
 

package/parser/index.ts

@@ -21,6 +21,8 @@ export type {
   ParsedStickyRegion,
   ParsedFlowItem,
   ParsedImageRegion,
+  ParsedIllustration,
+  IllustrationAnchor,
   GridYKeyword,
 } from './compositionParser';