brand-intent 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.15.0",
+  "version": "0.16.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

@@ -250,6 +250,14 @@ const VALID_STRATEGIES = new Set<PaletteStrategy>(['monochrome', 'duotone', 'tri
 const VALID_ADHERENCES = new Set<Adherence>(['strict', 'on-brand', 'flexible']);
 const TONE_CLASSES = new Set<ToneClass>(['light', 'mid', 'dark']);
 const FAMILY_ROLES = new Set<FamilyRole>(['core', 'accent', 'contrast']);
+
+const DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function isMonthDay(value: string): boolean {
+  const m = value.match(/^(\d{2})-(\d{2})$/);
+  if (!m) return false;
+  const month = Number(m[1]), day = Number(m[2]);
+  return month >= 1 && month <= 12 && day >= 1 && day <= DAYS_IN_MONTH[month - 1];
+}
 const FAMILY_ORDERS = new Set<FamilyOrder>(['cycle', 'sequence']);
 const FAMILY_BORROWS = new Set<FamilyBorrow>(['previous', 'next', 'both', 'none']);
 const PAIR_KEYS = ['ground', 'figure', 'text'] as const;
@@ -395,7 +403,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const adherenceOverridesRaw: Record<string, string> = {};
   const colorRulesRaw: Record<string, string> = {};
   let colorRulesDeclared = false;
-  type RawFamily = { name: string; line: number; colors: Array<{ role: string; value: string; line: number }>; pairs: Array<{ ground: string; figure: string; line: number }> };
+  type RawFamily = { name: string; line: number; from?: string; colors: Array<{ role: string; value: string; line: number }>; pairs: Array<{ ground: string; figure: string; line: number }> };
   const familiesProps: Record<string, string> = {};
   const familiesRaw: RawFamily[] = [];
   let familiesDeclared = false;
@@ -653,8 +661,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         const colonIdx = trimmed.indexOf(':');
         const key = colonIdx !== -1 ? trimmed.slice(0, colonIdx).trim() : trimmed;
+        if (key === 'from' && colonIdx !== -1) {
+          const value = trimmed.slice(colonIdx + 1).trim();
+          if (currentFamily.from !== undefined) throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}" declares from: twice`);
+          if (!isMonthDay(value)) throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}" from: must be "MM-DD" (e.g. 12-01), got "${value}"`);
+          inPairs = false;
+          currentFamily.from = value;
+          continue;
+        }
         if (colonIdx === -1 || !FAMILY_ROLES.has(key as FamilyRole)) {
-          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected core / accent / contrast / pairs, got "${trimmed}"`);
+          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected from / core / accent / contrast / pairs, got "${trimmed}"`);
         }
         inPairs = false;
         currentFamily.colors.push({ role: key, value: trimmed.slice(colonIdx + 1).trim(), line: lineNum });
@@ -1150,7 +1166,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         brandColors[c.key] = c.hex;
       }
-      families.push({ name: raw.name, colors, pairs: [] });
+      families.push({ name: raw.name, ...(raw.from ? { from: raw.from } : {}), colors, pairs: [] });
+    }
+    const dated = familiesRaw.filter(f => f.from !== undefined);
+    if (dated.length > 0 && dated.length < familiesRaw.length) {
+      const missing = familiesRaw.filter(f => f.from === undefined).map(f => f.name).join(', ');
+      throw new Error(`${fileName}: color-families: from: must be declared on every family or on none (missing: ${missing})`);
+    }
+    for (const f of dated) {
+      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 };
     if (borrow !== 'none' && reachCoversAll(families.length, { order, borrow, distance })) {

package/parser/colorSystem.ts

@@ -193,6 +193,23 @@ export function colorOrigin(
   return null;
 }
 
+/**
+ * Family in season on `date`: the one with the latest `from:` on or before that
+ * month/day, wrapping to the year's last start before the first one. Uses the
+ * date's local calendar day. -1 when the families declare no dates.
+ */
+export function familyIndexForDate(families: Pick<ColorFamily, 'from'>[], date: Date): number {
+  if (families.length === 0 || families.some(f => !f.from)) return -1;
+  const today = `${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  let best = -1;
+  let latest = -1;
+  families.forEach((f, i) => {
+    if (f.from! <= today && (best === -1 || f.from! > families[best].from!)) best = i;
+    if (latest === -1 || f.from! > families[latest].from!) latest = i;
+  });
+  return best !== -1 ? best : latest;
+}
+
 /** Name of the family that declares `hex` (first match), for error messages. */
 export function owningFamily(hex: string, families: ColorFamily[]): string | undefined {
   return families.find(f => f.colors.some(c => c.hex === hex))?.name;

package/parser/index.ts

@@ -20,6 +20,7 @@ export {
   familyTextCandidates,
   checkFamilyPair,
   enumerateFamilyPairs,
+  familyIndexForDate,
   DEFAULT_COLOR_RULES,
 } from './colorSystem';
 export type { ReachConfig } from './colorSystem';

package/parser/types.ts

@@ -156,6 +156,8 @@ export interface FamilyPair extends PairCheck {
 
 export interface ColorFamily {
   name: string;
+  /** Start date `MM-DD` (`from:`). Declared on every family or on none. */
+  from?: string;
   colors: FamilyColor[];
   pairs: FamilyPair[];
 }

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

@@ -15,6 +15,7 @@
     { "include": "#color-rules-entry" },
     { "include": "#color-families-property" },
     { "include": "#family-header" },
+    { "include": "#family-from" },
     { "include": "#family-role" },
     { "include": "#family-pairs-keyword" },
     { "include": "#color-mode-enum" },
@@ -143,6 +144,15 @@
         "5": { "name": "string.unquoted.brand-intent-brand" }
       }
     },
+    "family-from": {
+      "comment": "Family start date: from: MM-DD",
+      "match": "^(\\s{4,})(from)(:\\s*)(\\d{2}-\\d{2})\\s*$",
+      "captures": {
+        "2": { "name": "support.type.property-name.brand-intent-brand" },
+        "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
+        "4": { "name": "constant.numeric.brand-intent-brand" }
+      }
+    },
     "family-pairs-keyword": {
       "match": "^(\\s{4,})(pairs)\\s*$",
       "captures": {