brand-intent 0.16.0 → 0.18.0

package/package.json

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

package/parser/brandParser.ts

@@ -37,6 +37,8 @@ import {
   reachCoversAll,
 } from './colorSystem';
 import { parseIconSource, isIconId } from './icons';
+import { parseDateWindowRanges } from './dateWindows';
+import type { DateWindowRange } from './dateWindows';
 import type { ParsedIconDef } from './icons';
 
 // ── Parsed type ────────────────────────────────────────────────────────────────
@@ -116,6 +118,29 @@ export interface ParsedBrand {
   framings?: ParsedFramingDef[];
   /** Camera defaults (`camera` block). Absent → rear camera, no grid. */
   camera?: ParsedCameraDef;
+  /** Photo treatment (`photo-look` block). Absent → photos stay as taken. */
+  photoLook?: ParsedPhotoLookDef;
+  /** Named yearly date windows (`windows` block): name → ranges. Referenced by sample `@name` markers and photo `when:`. */
+  windows?: Record<string, DateWindowRange[]>;
+}
+
+export type PhotoLookKey = 'saturation' | 'contrast' | 'warmth' | 'fade' | 'mono' | 'duotone';
+
+export interface ParsedPhotoLookDef {
+  /** -100..100, 0 = unchanged. */
+  saturation: number;
+  /** -100..100, 0 = unchanged. */
+  contrast: number;
+  /** -100 (cool) .. 100 (warm), 0 = unchanged. */
+  warmth: number;
+  /** Lifted black point, 0..100. */
+  fade: number;
+  /** Grayscale (monochrome). */
+  mono: boolean;
+  /** Map luminance onto two colors (resolved hex), shadows → highlights. Excludes `mono`. */
+  duotone?: { shadow: string; highlight: string };
+  /** Keys the person cannot change. All others are starting values. */
+  fixed: PhotoLookKey[];
 }
 
 export interface ParsedCameraDef {
@@ -171,6 +196,8 @@ export interface ParsedAssetDef {
   alignVariants?: Partial<Record<LogoAlign, { src: string; aspectRatio?: number }>>;
   /** Library group (e.g. "experimental"). Consumers list each group as its own section after the ungrouped assets. */
   group?: string;
+  /** Photos only: name of the date window the photo fits (`when:`). Absent → all year. */
+  when?: string;
 }
 
 export type LogoAlign = 'left' | 'center' | 'right';
@@ -380,7 +407,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta' | 'icons' | 'counter' | 'framing' | 'camera';
+  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta' | 'icons' | 'counter' | 'framing' | 'camera' | 'photo-look' | 'windows';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -429,6 +456,10 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   let counterDeclared = false;
   const cameraRaw: Record<string, { value: string; line: number }> = {};
   let cameraDeclared = false;
+  const photoLookRaw: Record<string, { value: string; line: number }> = {};
+  let photoLookDeclared = false;
+  const windowsRaw: Array<{ name: string; value: string; line: number }> = [];
+  let windowsDeclared = false;
   const framingsRaw: Array<{ id: string; line: number; props: Record<string, { value: string; line: number }> }> = [];
 
   for (let i = 0; i < lines.length; i++) {
@@ -817,6 +848,27 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         cameraRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
         continue;
       }
+      if (activeBlock === 'photo-look') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        // `# …` is a comment, but `#RGB` / `#RRGGBB` is a duotone color
+        const commentIdx = trimmed.search(/\s+#(?![0-9a-f]{3}(?:[0-9a-f]{3}(?:[0-9a-f]{2})?)?(?:\s|$))/i);
+        const entry = commentIdx !== -1 ? trimmed.slice(0, commentIdx) : trimmed;
+        const colonIdx = entry.indexOf(':');
+        // Bare flag (`mono`) or KEY: VALUE
+        if (colonIdx === -1) photoLookRaw[entry.trim()] = { value: '', line: lineNum };
+        else photoLookRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
+        continue;
+      }
+      if (activeBlock === 'windows') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        const entry = trimmed.replace(/\s+#.*$/, '');
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1) throw new Error(`${fileName}:${lineNum}: window must be "NAME: MM-DD..MM-DD", got "${trimmed}"`);
+        windowsRaw.push({ name: entry.slice(0, colonIdx).trim(), value: entry.slice(colonIdx + 1).trim(), line: lineNum });
+        continue;
+      }
       if (activeBlock === 'framing') {
         const trimmed = raw.trim();
         if (trimmed.startsWith('#')) continue;
@@ -897,6 +949,22 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
+    // photo-look — photo treatment (saturation)
+    if (raw.trim() === 'photo-look') {
+      if (photoLookDeclared) throw new Error(`${fileName}:${lineNum}: duplicate photo-look block`);
+      photoLookDeclared = true;
+      activeBlock = 'photo-look';
+      continue;
+    }
+
+    // windows — named yearly date windows
+    if (raw.trim() === 'windows') {
+      if (windowsDeclared) throw new Error(`${fileName}:${lineNum}: duplicate windows block`);
+      windowsDeclared = true;
+      activeBlock = 'windows';
+      continue;
+    }
+
     // framing <id> — photo framing module (horizon position)
     const framingMatch = raw.match(/^framing\s+(\S+)\s*$/);
     if (framingMatch) {
@@ -1456,6 +1524,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (raw.props['gltf']) def.gltfSrc = raw.props['gltf'];
     if (raw.props['generator']) def.generator = raw.props['generator'];
     if (raw.props['group']) def.group = raw.props['group'];
+    if (raw.props['when']) def.when = raw.props['when'];
     // generator-params are stored as "generator-params.KEY" by the sub-block parser.
     const paramEntries: [string, number][] = [];
     for (const [k, v] of Object.entries(raw.props)) {
@@ -1475,6 +1544,26 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     }
     return def;
   };
+  // Finalise date windows (before assets: photo `when:` references them)
+  if (windowsDeclared) {
+    const windows: Record<string, DateWindowRange[]> = {};
+    for (const w of windowsRaw) {
+      if (!/^[a-z][a-z0-9-]*$/.test(w.name)) throw new Error(`${fileName}:${w.line}: window name must be lowercase kebab-case, got "${w.name}"`);
+      if (windows[w.name]) throw new Error(`${fileName}:${w.line}: duplicate window "${w.name}"`);
+      try { windows[w.name] = parseDateWindowRanges(w.value); }
+      catch (e) { throw new Error(`${fileName}:${w.line}: window "${w.name}": ${(e as Error).message}`); }
+    }
+    result.windows = windows;
+  }
+  for (const [kind, arr] of [['logo', logosRaw], ['video', videosRaw], ['illustration', illustrationsRaw]] as const) {
+    const a = arr.find(r => r.props['when']);
+    if (a) throw new Error(`${fileName}: ${kind} "${a.id}": when: is for photos only`);
+  }
+  for (const p of photosRaw) {
+    const when = p.props['when'];
+    if (when && !result.windows?.[when]) throw new Error(`${fileName}: photo "${p.id}" references unknown window "${when}"`);
+  }
+
   if (logosRaw.length > 0 || photosRaw.length > 0 || videosRaw.length > 0 || illustrationsRaw.length > 0) {
     result.assets = {};
     if (logosRaw.length > 0) result.assets.logos = logosRaw.map(toAssetDef);
@@ -1582,6 +1671,60 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     result.camera = camera;
   }
 
+  // Finalise photo treatment
+  if (photoLookDeclared) {
+    const keys: PhotoLookKey[] = ['saturation', 'contrast', 'warmth', 'fade', 'mono', 'duotone'];
+    for (const [key, { line }] of Object.entries(photoLookRaw)) {
+      if (key !== 'fixed' && !keys.includes(key as PhotoLookKey)) throw new Error(`${fileName}:${line}: unknown photo-look property "${key}"`);
+    }
+    const int = (key: string, min: number, max: number): number => {
+      const p = photoLookRaw[key];
+      if (!p) return 0;
+      const n = Number(p.value);
+      if (!/^[+-]?\d+$/.test(p.value) || n < min || n > max) {
+        throw new Error(`${fileName}:${p.line}: photo-look ${key} must be an integer from ${min} to ${max}, got "${p.value}"`);
+      }
+      return n;
+    };
+    const look: ParsedPhotoLookDef = {
+      saturation: int('saturation', -100, 100),
+      contrast: int('contrast', -100, 100),
+      warmth: int('warmth', -100, 100),
+      fade: int('fade', 0, 100),
+      mono: false,
+      fixed: [],
+    };
+    const mono = photoLookRaw['mono'];
+    if (mono) {
+      if (mono.value !== '') throw new Error(`${fileName}:${mono.line}: photo-look mono is a flag and takes no value`);
+      look.mono = true;
+    }
+    const duo = photoLookRaw['duotone'];
+    if (duo) {
+      if (mono) throw new Error(`${fileName}:${duo.line}: photo-look cannot be both mono and duotone`);
+      const refs = duo.value.split(/\s+/);
+      if (refs.length !== 2) throw new Error(`${fileName}:${duo.line}: photo-look duotone must be "SHADOW HIGHLIGHT", got "${duo.value}"`);
+      const [shadow, highlight] = refs.map(ref => {
+        if (ref.startsWith('$') && !brandColors[ref.slice(1)]) {
+          throw new Error(`${fileName}:${duo.line}: photo-look duotone references unknown brand color "${ref}"`);
+        }
+        const hex = normalizeHex(ref.startsWith('$') ? brandColors[ref.slice(1)] : ref);
+        if (!hex) throw new Error(`${fileName}:${duo.line}: photo-look duotone colors must be $ref or #HEX, got "${ref}"`);
+        return hex;
+      });
+      look.duotone = { shadow, highlight };
+    }
+    const fixed = photoLookRaw['fixed'];
+    if (fixed) {
+      for (const key of fixed.value.split(/\s+/)) {
+        if (!keys.includes(key as PhotoLookKey)) throw new Error(`${fileName}:${fixed.line}: photo-look fixed lists unknown key "${key}"`);
+        if (!photoLookRaw[key]) throw new Error(`${fileName}:${fixed.line}: photo-look fixed lists "${key}", which is not set`);
+        look.fixed.push(key as PhotoLookKey);
+      }
+    }
+    result.photoLook = look;
+  }
+
   // Finalise framing modules
   if (framingsRaw.length > 0) {
     const known = new Set(['label', 'horizon', 'description']);

package/parser/dateWindows.ts

@@ -0,0 +1,34 @@
+// Date windows — named yearly date ranges (`windows` block in .brand).
+// Samples (`@name`) and brand photos (`when:`) that only fit part of the year reference them.
+
+/** One yearly range, inclusive, as `MM-DD`. `from` after `to` wraps over the year end. */
+export interface DateWindowRange {
+  from: string;
+  to: string;
+}
+
+const DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+/** Parse `MM-DD..MM-DD[, MM-DD..MM-DD …]`. Throws a message without file/line prefix. */
+export function parseDateWindowRanges(value: string): DateWindowRange[] {
+  const parts = value.split(',').map(p => p.trim());
+  if (parts.length === 0 || parts.some(p => !p)) throw new Error(`expected "MM-DD..MM-DD", got "${value}"`);
+  return parts.map(part => {
+    const m = part.match(/^(\d{2}-\d{2})\.\.(\d{2}-\d{2})$/);
+    if (!m) throw new Error(`expected "MM-DD..MM-DD", got "${part}"`);
+    for (const md of [m[1], m[2]]) {
+      const [month, day] = md.split('-').map(Number);
+      if (month < 1 || month > 12 || day < 1 || day > DAYS_IN_MONTH[month - 1]) throw new Error(`invalid date "${md}"`);
+    }
+    return { from: m[1], to: m[2] };
+  });
+}
+
+/** True when `date` (local calendar day) falls in any of the ranges. */
+export function isInDateWindow(ranges: DateWindowRange[], date: Date): boolean {
+  const key = `${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  return ranges.some(({ from, to }) => (from <= to ? key >= from && key <= to : key >= from || key <= to));
+}
+
+/** Trailing window marker on a sample line: `Raps blüht im Mai  @rapsbluete`. */
+export const SAMPLE_WINDOW_MARKER = /\s+@([a-z][a-z0-9-]*)\s*$/;

package/parser/index.ts

@@ -24,7 +24,10 @@ export {
   DEFAULT_COLOR_RULES,
 } from './colorSystem';
 export type { ReachConfig } from './colorSystem';
-export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape, ParsedFramingDef, ParsedCameraDef } from './brandParser';
+export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape, ParsedFramingDef, ParsedCameraDef, ParsedPhotoLookDef, PhotoLookKey } from './brandParser';
+
+export { parseDateWindowRanges, isInDateWindow, SAMPLE_WINDOW_MARKER } from './dateWindows';
+export type { DateWindowRange } from './dateWindows';
 
 export { parseIconRef, parseIconSource, resolveIconRef, parseListItem, phosphorName, PHOSPHOR_WEIGHTS } from './icons';
 export type { IconRef, IconSource, ParsedIconDef, ResolvedIcon, PhosphorWeight } from './icons';

package/parser/purposeParser.ts

@@ -8,6 +8,7 @@
 import type { SlotId } from './types';
 import { parseIconRef, parseListItem } from './icons';
 import type { IconRef } from './icons';
+import { SAMPLE_WINDOW_MARKER } from './dateWindows';
 
 // ── Parsed types ──────────────────────────────────────────────────────────────
 
@@ -55,6 +56,9 @@ export interface ParsedPurposeSlot {
   label: string;
   /** Sample text variants for this slot. Picked randomly on page creation. */
   samples: string[];
+  /** Date window per sample (parallel to `samples`), from a trailing `@name` marker; undefined = all year.
+   *  Absent when no sample in the slot has a marker. Names resolve against the `.brand` `windows` block. */
+  sampleWindows?: (string | undefined)[];
   /** Fixed value — when set, this slot is never AI-generated or shuffled. Mutually exclusive with samples. */
   value?: string;
   maxLength: number;
@@ -166,6 +170,18 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
       s.marker = 'icon';
     }
     if (s.defaultIcon && s.marker !== 'icon') throw new Error(`${fileName}:${lineNum}: slot "${s.id}": defaultIcon needs "marker: icon"`);
+    if (!s.value && s.samples) {
+      // Trailing `@name` window marker, on the sample's first line only
+      const windows = s.samples.map((sample, i) => {
+        const [first, ...rest] = sample.split('\n');
+        if (rest.some(l => SAMPLE_WINDOW_MARKER.test(l))) throw new Error(`${fileName}:${lineNum}: slot "${s.id}": window marker belongs on the sample's first line ("${rest.find(l => SAMPLE_WINDOW_MARKER.test(l))}")`);
+        const m = first.match(SAMPLE_WINDOW_MARKER);
+        if (!m) return undefined;
+        s.samples![i] = [first.slice(0, m.index).trimEnd(), ...rest].join('\n');
+        return m[1];
+      });
+      if (windows.some(Boolean)) s.sampleWindows = windows;
+    }
     if (s.slotType === 'list') {
       for (const sample of s.samples ?? []) {
         for (const item of sample.split('\n')) {

package/vscode-extension/syntaxes/brand.tmLanguage.json

@@ -30,6 +30,7 @@
     { "include": "#color-group-reference" },
     { "include": "#color-group-entry-property" },
     { "include": "#icons-counter-header" },
+    { "include": "#window-entry" },
     { "include": "#icon-entry" },
     { "include": "#counter-value" },
     { "include": "#framing-horizon" },
@@ -399,8 +400,8 @@
       }
     },
     "icons-counter-header": {
-      "comment": "Bare `icons` / `counter` block headers.",
-      "match": "^(icons|counter)\\s*$",
+      "comment": "Bare `icons` / `counter` / `camera` / `photo-look` / `windows` block headers.",
+      "match": "^(icons|counter|camera|photo-look|windows)\\s*$",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" }
       }
@@ -421,6 +422,16 @@
         "11": { "name": "comment.line.number-sign.brand-intent-brand" }
       }
     },
+    "window-entry": {
+      "comment": "windows entry: NAME: MM-DD..MM-DD[, MM-DD..MM-DD]",
+      "match": "^(\\s{2,})([a-z][a-z0-9-]*)(:\\s*)(\\d{2}-\\d{2}\\.\\.\\d{2}-\\d{2}(?:\\s*,\\s*\\d{2}-\\d{2}\\.\\.\\d{2}-\\d{2})*)\\s*(#.*)?$",
+      "captures": {
+        "2": { "name": "variable.other.brand-intent-brand" },
+        "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
+        "4": { "name": "constant.numeric.brand-intent-brand" },
+        "5": { "name": "comment.line.number-sign.brand-intent-brand" }
+      }
+    },
     "framing-horizon": {
       "comment": "framing block horizon: N% | none",
       "match": "^(\\s{2,})(horizon)(:\\s*)(\\d+(?:\\.\\d+)?%|none)\\s*(#.*)?$",
@@ -466,7 +477,7 @@
     },
     "keyword-partial": {
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
-      "match": "^(id:|name:|language:|locale:|domain:|app-icon:|favicon:|og-image:|tokens:|figma-file-key:|figma-collection:|tokens-file:|spacing:|label:|cta:|color-mode:|color-strategy:|color-adherence:|brand-colors|state-colors|color-bounds|color-rules|color-families|theme|divider|font|typography|logo|photo|video|illustration|icons|counter|framing)(?=\\s|$)",
+      "match": "^(id:|name:|language:|locale:|domain:|app-icon:|favicon:|og-image:|tokens:|figma-file-key:|figma-collection:|tokens-file:|spacing:|label:|cta:|color-mode:|color-strategy:|color-adherence:|brand-colors|state-colors|color-bounds|color-rules|color-families|theme|divider|font|typography|logo|photo|video|illustration|icons|counter|framing|windows)(?=\\s|$)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" }
       }

package/vscode-extension/syntaxes/purpose.tmLanguage.json

@@ -24,6 +24,7 @@
     { "include": "#list-property" },
     { "include": "#sample-item" },
     { "include": "#sample-icon-continuation" },
+    { "include": "#sample-window" },
     { "include": "#property" },
     { "include": "#keyword-partial" }
   ],
@@ -246,6 +247,13 @@
         "2": { "name": "entity.name.function.brand-intent-purpose" }
       }
     },
+    "sample-window": {
+      "comment": "Trailing @name date-window marker on a sample line",
+      "match": "(?<=\\s)(@[a-z][a-z0-9-]*)\\s*$",
+      "captures": {
+        "1": { "name": "variable.other.brand-intent-purpose" }
+      }
+    },
     "keyword-partial": {
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
       "patterns": [