brand-intent 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.17.0",
+  "version": "0.19.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 ────────────────────────────────────────────────────────────────
@@ -118,6 +120,8 @@ export interface ParsedBrand {
   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';
@@ -131,7 +135,7 @@ export interface ParsedPhotoLookDef {
   warmth: number;
   /** Lifted black point, 0..100. */
   fade: number;
-  /** Black-and-white. */
+  /** Grayscale (monochrome). */
   mono: boolean;
   /** Map luminance onto two colors (resolved hex), shadows → highlights. Excludes `mono`. */
   duotone?: { shadow: string; highlight: string };
@@ -192,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';
@@ -401,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' | 'photo-look';
+  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 = '';
@@ -452,6 +458,8 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   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++) {
@@ -852,6 +860,15 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         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;
@@ -940,6 +957,14 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       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) {
@@ -1177,13 +1202,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (!Number.isInteger(distance) || distance < 1) throw new Error(`${fileName}: color-families distance must be a whole number ≥ 1, got "${familiesProps.distance}"`);
     if (familiesRaw.length === 0) throw new Error(`${fileName}: color-families declares no family`);
 
-    const shared: Array<{ name: string; hex: string }> = [];
-    for (const ref of (familiesProps.shared ?? '').split(',').map(r => r.trim()).filter(Boolean)) {
-      if (!ref.startsWith('$')) throw new Error(`${fileName}: color-families shared entries must be $refs to brand-colors, got "${ref}"`);
-      const hex = brandColors[ref.slice(1)] ? normalizeHex(brandColors[ref.slice(1)]) : null;
-      if (!hex || !isHex6(hex)) throw new Error(`${fileName}: color-families shared "${ref}" is not a known 6-digit brand color`);
-      shared.push({ name: ref.slice(1), hex });
-    }
+    /** Comma-separated `$refs` to brand-colors (`shared:`, `photo-fallback:`). */
+    const colorRefs = (key: string): Array<{ name: string; hex: string }> =>
+      (familiesProps[key] ?? '').split(',').map(r => r.trim()).filter(Boolean).map(ref => {
+        if (!ref.startsWith('$')) throw new Error(`${fileName}: color-families ${key} entries must be $refs to brand-colors, got "${ref}"`);
+        const hex = brandColors[ref.slice(1)] ? normalizeHex(brandColors[ref.slice(1)]) : null;
+        if (!hex || !isHex6(hex)) throw new Error(`${fileName}: color-families ${key} "${ref}" is not a known 6-digit brand color`);
+        return { name: ref.slice(1), hex };
+      });
+    const shared = colorRefs('shared');
+    const photoFallback = colorRefs('photo-fallback');
 
     const families: ColorFamily[] = [];
     for (const raw of familiesRaw) {
@@ -1220,7 +1248,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       const twin = dated.find(o => o !== f && o.from === f.from);
       if (twin) throw new Error(`${fileName}:${f.line}: families "${twin.name}" and "${f.name}" share from: ${f.from}`);
     }
-    colorFamilies = { order, borrow, distance, shared, families };
+    colorFamilies = { order, borrow, distance, shared, ...(photoFallback.length > 0 ? { photoFallback } : {}), families };
     if (borrow !== 'none' && reachCoversAll(families.length, { order, borrow, distance })) {
       colorWarnings.push(`color-families: borrow "${borrow}" with distance ${distance} reaches every family — the borrow rule has no effect`);
     }
@@ -1499,6 +1527,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)) {
@@ -1518,6 +1547,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);

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

@@ -26,6 +26,9 @@ export {
 export type { ReachConfig } from './colorSystem';
 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';
 export type {

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/parser/types.ts

@@ -168,6 +168,9 @@ export interface ColorFamilies {
   distance: number;
   /** Colors allowed in every family (resolved from `shared:` refs). */
   shared: Array<{ name: string; hex: string }>;
+  /** Text and figure colors for photos no pair reads on, in order of preference (`photo-fallback:` refs).
+   *  Used only over photos, never in pairs or guided generation. Absent when not declared. */
+  photoFallback?: Array<{ name: string; hex: string }>;
   families: ColorFamily[];
 }
 

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" },
@@ -119,8 +120,8 @@
       }
     },
     "color-families-property": {
-      "comment": "Block keys under color-families: order/borrow/distance/shared",
-      "match": "^( {2})(order|borrow|distance|shared)(:\\s*)(.+)$",
+      "comment": "Block keys under color-families: order/borrow/distance/shared/photo-fallback",
+      "match": "^( {2})(order|borrow|distance|shared|photo-fallback)(:\\s*)(.+)$",
       "captures": {
         "2": { "name": "support.type.property-name.brand-intent-brand" },
         "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
@@ -399,8 +400,8 @@
       }
     },
     "icons-counter-header": {
-      "comment": "Bare `icons` / `counter` / `camera` / `photo-look` block headers.",
-      "match": "^(icons|counter|camera|photo-look)\\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": [