rafters 0.0.48 → 0.0.51

package/README.md

@@ -68,25 +68,47 @@ pnpm dlx rafters studio
 
 Four tools give AI agents complete design system access:
 
-### `rafters_vocabulary`
+### `rafters_composite`
 
-System overview. Colors, spacing, typography, components, cognitive loads, and available patterns. Call this first to orient.
+Query composites by ID, search term, or category. Returns designer intent (solves, appliesWhen, do/never), I/O rules for chaining, and block structure.
+
+```json
+{ "id": "heading" }           // Get specific composite
+{ "query": "form" }           // Fuzzy search
+{ "category": "typography" }  // Filter by category
+```
 
 ### `rafters_pattern`
 
-Deep guidance for specific UI scenarios. Returns which components to use, which tokens to apply, accessibility requirements, and do/never rules.
+Design pattern guidance by querying composites. Search by what the pattern solves or use fuzzy search.
+
+```json
+{ "solves": "hierarchy" }      // Find patterns for document hierarchy
+{ "solves": "authentication" } // Find patterns for auth flows
+{ "query": "form" }            // Fuzzy search across composites
+```
 
-**Available patterns:** `destructive-action`, `form-validation`, `empty-state`, `loading-state`, `navigation-hierarchy`, `data-table`, `modal-dialog`, `tooltip-guidance`, `card-layout`, `dropdown-actions`
+Returns composites with usagePatterns (do/never rules), cognitive load, and designer intent.
 
-### `rafters_component`
+### `rafters_rule`
 
-Full intelligence for a specific component. Cognitive load rating, attention economics, accessibility requirements, trust-building patterns, variants, sizes, and primitives.
+Query validation rules or create new ones. Rules are named validation patterns that composites can apply.
 
-### `rafters_token`
+```json
+{}                    // List all rules
+{ "name": "email" }   // Get specific rule
+{ "query": "pass" }   // Search rules
+```
+
+**Built-in rules:** `required`, `email`, `password`, `url`, `credentials`
+
+### `rafters_component`
 
-Token dependency graph, derivation rules, and human override context. Returns how a token is computed, what it depends on, and whether a designer manually overrode it (with their reasoning).
+Full intelligence for a specific component. Cognitive load rating, attention economics, accessibility requirements, trust-building patterns, variants, sizes, and primitives.
 
-**Derivation rules:** `calc()`, `state:hover`, `scale:600`, `contrast:auto`, `invert`
+```json
+{ "name": "button" }
+```
 
 ## How It Works
 

package/dist/calc-ICOTQANG.js

@@ -0,0 +1,8 @@
+import {
+  calc_default
+} from "./chunk-2RHKE2AP.js";
+import "./chunk-WG6NCWQ2.js";
+import "./chunk-R5U7XKVJ.js";
+export {
+  calc_default as default
+};

package/dist/chunk-2RHKE2AP.js

@@ -0,0 +1,344 @@
+import {
+  definePlugin,
+  external_exports
+} from "./chunk-WG6NCWQ2.js";
+
+// ../math-utils/src/constants.ts
+var MUSICAL_RATIOS = {
+  "minor-second": 1.067,
+  // 16:15 ratio - tight, subtle progression
+  "major-second": 1.125,
+  // 9:8 ratio - gentle, natural progression
+  "minor-third": 1.2,
+  // 6:5 ratio - moderate, balanced progression
+  "major-third": 1.25,
+  // 5:4 ratio - strong, noticeable progression
+  "perfect-fourth": 1.333,
+  // 4:3 ratio - bold, architectural progression
+  "augmented-fourth": Math.SQRT2,
+  // √2 ratio (tritone) - dramatic, modern
+  "perfect-fifth": 1.5
+  // 3:2 ratio - classical, powerful progression
+};
+var MATHEMATICAL_CONSTANTS = {
+  // Golden Ratio - appears in nature, art, and classical architecture
+  golden: 1.618033988749,
+  // φ (phi) - most pleasing proportion to human eye
+  "golden-ratio": 1.618033988749,
+  // Alternative name
+  // Square Root Ratios
+  sqrt2: Math.SQRT2,
+  // √2 ≈ 1.414 - A4 paper ratio, diagonal harmony
+  sqrt3: Math.sqrt(3),
+  // √3 ≈ 1.732 - equilateral triangle ratio
+  sqrt5: Math.sqrt(5),
+  // √5 ≈ 2.236 - related to golden ratio
+  // Mathematical Constants
+  e: Math.E,
+  // Euler's number ≈ 2.718 - natural exponential
+  pi: Math.PI,
+  // π ≈ 3.142 - circular proportions
+  // Common Design Ratios
+  silver: 1 + Math.SQRT2
+  // Silver ratio ≈ 2.414 - alternative to golden
+};
+var ALL_RATIOS = {
+  ...MUSICAL_RATIOS,
+  ...MATHEMATICAL_CONSTANTS
+};
+var AVAILABLE_RATIOS_STRING = Object.keys(ALL_RATIOS).join(", ");
+function getRatio(name) {
+  const ratio = ALL_RATIOS[name];
+  if (ratio === void 0) {
+    throw new Error(`Unknown ratio: ${name}. Available ratios: ${AVAILABLE_RATIOS_STRING}`);
+  }
+  return ratio;
+}
+
+// ../math-utils/src/calculations.ts
+function tokenize(expr) {
+  const tokens = [];
+  let current = "";
+  for (let i = 0; i < expr.length; i++) {
+    const char = expr[i];
+    if (!char) continue;
+    if (char === " ") {
+      continue;
+    }
+    if ("+-*/()".includes(char)) {
+      if (current) {
+        const num = parseFloat(current);
+        if (!Number.isNaN(num)) {
+          tokens.push(num);
+        }
+        current = "";
+      }
+      tokens.push(char);
+    } else if (char) {
+      current += char;
+    }
+  }
+  if (current) {
+    const num = parseFloat(current);
+    if (!Number.isNaN(num)) {
+      tokens.push(num);
+    }
+  }
+  return tokens;
+}
+var ExpressionParser = class {
+  tokens;
+  position;
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.position = 0;
+  }
+  current() {
+    return this.tokens[this.position];
+  }
+  consume() {
+    return this.tokens[this.position++];
+  }
+  parse() {
+    const result = this.expression();
+    if (this.position < this.tokens.length) {
+      throw new Error("Unexpected token after expression");
+    }
+    return result;
+  }
+  expression() {
+    let left = this.term();
+    while (this.current() === "+" || this.current() === "-") {
+      const op = this.consume();
+      const right = this.term();
+      if (op === "+") {
+        left = left + right;
+      } else {
+        left = left - right;
+      }
+    }
+    return left;
+  }
+  term() {
+    let left = this.factor();
+    while (this.current() === "*" || this.current() === "/") {
+      const op = this.consume();
+      const right = this.factor();
+      if (op === "*") {
+        left = left * right;
+      } else {
+        if (right === 0) {
+          throw new Error("Division by zero");
+        }
+        left = left / right;
+      }
+    }
+    return left;
+  }
+  factor() {
+    const token = this.current();
+    if (typeof token === "number") {
+      this.consume();
+      return token;
+    }
+    if (token === "(") {
+      this.consume();
+      const result = this.expression();
+      if (this.current() !== ")") {
+        throw new Error("Missing closing parenthesis");
+      }
+      this.consume();
+      return result;
+    }
+    if (token === "-") {
+      this.consume();
+      return -this.factor();
+    }
+    throw new Error(`Unexpected token: ${token}`);
+  }
+};
+function evaluateExpression(expression, variables = {}) {
+  let processedExpression = expression.trim();
+  for (const [varName, varValue] of Object.entries(variables)) {
+    const bracedVarRegex = new RegExp(`\\{${varName.replace("-", "\\-")}\\}`, "g");
+    processedExpression = processedExpression.replace(bracedVarRegex, String(varValue));
+  }
+  for (const [ratioName, ratioValue] of Object.entries(ALL_RATIOS)) {
+    const ratioRegex = new RegExp(`\\b${ratioName.replace("-", "\\-")}\\b`, "g");
+    processedExpression = processedExpression.replace(ratioRegex, String(ratioValue));
+  }
+  for (const [varName, varValue] of Object.entries(variables)) {
+    const varRegex = new RegExp(`\\b${varName.replace("-", "\\-")}\\b`, "g");
+    processedExpression = processedExpression.replace(varRegex, String(varValue));
+  }
+  try {
+    const tokens = tokenize(processedExpression);
+    const parser = new ExpressionParser(tokens);
+    const result = parser.parse();
+    if (typeof result !== "number" || !Number.isFinite(result)) {
+      throw new Error(`Invalid calculation result: ${result}`);
+    }
+    return result;
+  } catch (error) {
+    throw new Error(`Cannot evaluate expression: ${expression} - ${error}`);
+  }
+}
+
+// ../math-utils/src/progressions.ts
+function createProgression(type) {
+  if (type === "linear") {
+    return {
+      type,
+      ratio: 1,
+      compute(base, step) {
+        return base * (step + 1);
+      },
+      generateSequence(base, steps, options = {}) {
+        const { includeZero = false, startStep = 0 } = options;
+        const result = [];
+        for (let i = 0; i < steps; i++) {
+          const step = startStep + i;
+          if (i === 0 && includeZero) {
+            result.push(0);
+          } else {
+            result.push(base * (step + 1));
+          }
+        }
+        return result;
+      }
+    };
+  }
+  if (type === "exponential") {
+    const defaultMultiplier = 1.25;
+    return {
+      type,
+      ratio: defaultMultiplier,
+      compute(base, step) {
+        return base * defaultMultiplier ** step;
+      },
+      generateSequence(base, steps, options = {}) {
+        const { includeZero = false, startStep = 0 } = options;
+        const result = [];
+        for (let i = 0; i < steps; i++) {
+          const step = startStep + i;
+          if (i === 0 && includeZero) {
+            result.push(0);
+          } else {
+            result.push(base * defaultMultiplier ** step);
+          }
+        }
+        return result;
+      }
+    };
+  }
+  const ratio = getRatio(type);
+  return {
+    type,
+    ratio,
+    compute(base, step) {
+      return base * ratio ** step;
+    },
+    generateSequence(base, steps, options = {}) {
+      const { includeZero = false, startStep = 0 } = options;
+      const result = [];
+      for (let i = 0; i < steps; i++) {
+        const step = startStep + i;
+        if (i === 0 && includeZero) {
+          result.push(0);
+        } else {
+          result.push(base * ratio ** step);
+        }
+      }
+      return result;
+    }
+  };
+}
+function generateProgression(type, options) {
+  const { baseValue, steps, multiplier = 1.25, includeZero = false } = options;
+  const result = [];
+  let cachedRatio;
+  for (let i = 0; i < steps; i++) {
+    let value;
+    switch (type) {
+      case "linear":
+        value = i === 0 && includeZero ? 0 : baseValue * (includeZero ? i : i + 1);
+        break;
+      case "exponential":
+        value = i === 0 && includeZero ? 0 : baseValue * multiplier ** (includeZero ? i - 1 : i);
+        break;
+      default:
+        try {
+          if (!cachedRatio) {
+            cachedRatio = getRatio(type);
+          }
+          value = i === 0 && includeZero ? 0 : baseValue * cachedRatio ** (includeZero ? i - 1 : i);
+        } catch (error) {
+          throw new Error(`Invalid progression type: ${type}`, { cause: error });
+        }
+    }
+    result.push(value);
+  }
+  return result;
+}
+function generateModularScale(ratio, baseSize, steps = 5) {
+  const ratioValue = typeof ratio === "number" ? ratio : getRatio(ratio);
+  const smaller = [];
+  const larger = [];
+  for (let i = 1; i <= steps; i++) {
+    smaller.unshift(baseSize / ratioValue ** i);
+  }
+  for (let i = 1; i <= steps; i++) {
+    larger.push(baseSize * ratioValue ** i);
+  }
+  return {
+    smaller,
+    base: baseSize,
+    larger
+  };
+}
+
+// ../design-tokens/src/plugins/calc.ts
+var CalcInputSchema = external_exports.object({
+  expression: external_exports.string(),
+  tokenValues: external_exports.record(external_exports.string(), external_exports.string())
+});
+var calc_default = definePlugin({
+  id: "calc",
+  input: CalcInputSchema,
+  output: external_exports.string(),
+  transform(input) {
+    let expression = input.expression;
+    let detectedUnit = "";
+    const numericValues = {};
+    for (const [tokenName, tokenValue] of Object.entries(input.tokenValues)) {
+      const numericValue = parseFloat(tokenValue);
+      if (Number.isNaN(numericValue)) {
+        throw new Error(`Token ${tokenName} value "${tokenValue}" is not numeric`);
+      }
+      if (!detectedUnit) {
+        const unitMatch = tokenValue.match(/([a-z%]+)$/i);
+        if (unitMatch?.[1]) {
+          detectedUnit = unitMatch[1];
+        }
+      }
+      numericValues[tokenName] = numericValue;
+      expression = expression.replace(new RegExp(`\\{${tokenName}\\}`, "g"), String(numericValue));
+    }
+    if (!detectedUnit) {
+      const literalUnitMatch = expression.match(/\d+([a-z%]+)/i);
+      if (literalUnitMatch?.[1]) {
+        detectedUnit = literalUnitMatch[1];
+      }
+    }
+    const result = evaluateExpression(expression);
+    return detectedUnit ? `${result}${detectedUnit}` : String(result);
+  }
+});
+
+export {
+  getRatio,
+  createProgression,
+  generateProgression,
+  generateModularScale,
+  calc_default
+};

package/dist/chunk-ACFX3U2C.js

@@ -0,0 +1,21 @@
+import {
+  definePlugin,
+  external_exports
+} from "./chunk-WG6NCWQ2.js";
+
+// ../design-tokens/src/plugins/example.ts
+var ExampleInputSchema = external_exports.object({
+  tokenName: external_exports.string()
+});
+var example_default = definePlugin({
+  id: "example",
+  input: ExampleInputSchema,
+  output: external_exports.string(),
+  transform(input) {
+    return `example-result-for-${input.tokenName}`;
+  }
+});
+
+export {
+  example_default
+};

package/dist/chunk-D6XDGJFN.js

@@ -0,0 +1,33 @@
+import {
+  ColorReferenceSchema,
+  ColorValueSchema,
+  INDEX_TO_POSITION,
+  definePlugin,
+  external_exports
+} from "./chunk-WG6NCWQ2.js";
+
+// ../design-tokens/src/plugins/scale.ts
+var ScalePositionInputSchema = external_exports.object({
+  familyColorValue: ColorValueSchema,
+  familyName: external_exports.string(),
+  scalePosition: external_exports.number().int().min(0).max(10)
+});
+var scale_default = definePlugin({
+  id: "scale-position",
+  input: ScalePositionInputSchema,
+  output: ColorReferenceSchema,
+  transform(input) {
+    const position = INDEX_TO_POSITION[input.scalePosition];
+    if (position === void 0) {
+      throw new Error(`Invalid scale position index: ${input.scalePosition}`);
+    }
+    return {
+      family: input.familyName,
+      position
+    };
+  }
+});
+
+export {
+  scale_default
+};

package/dist/chunk-J73HHGWC.js

@@ -0,0 +1,44 @@
+import {
+  ColorReferenceSchema,
+  ColorValueSchema,
+  INDEX_TO_POSITION,
+  definePlugin,
+  external_exports
+} from "./chunk-WG6NCWQ2.js";
+
+// ../design-tokens/src/plugins/state.ts
+var StateInputSchema = external_exports.object({
+  familyColorValue: ColorValueSchema,
+  familyName: external_exports.string(),
+  basePosition: external_exports.number().int().min(0).max(10),
+  stateType: external_exports.enum(["hover", "active", "focus", "disabled"])
+});
+var STATE_OFFSETS = {
+  hover: 1,
+  active: 2,
+  focus: 1,
+  disabled: -2
+};
+var state_default = definePlugin({
+  id: "state",
+  input: StateInputSchema,
+  output: ColorReferenceSchema,
+  transform(input) {
+    const colorValue = input.familyColorValue;
+    const precomputed = colorValue.stateReferences?.[input.stateType];
+    if (precomputed) {
+      return {
+        family: precomputed.family,
+        position: String(precomputed.position)
+      };
+    }
+    const offset = STATE_OFFSETS[input.stateType];
+    const adjustedIndex = Math.max(0, Math.min(10, input.basePosition + offset));
+    const position = INDEX_TO_POSITION[adjustedIndex] ?? "500";
+    return { family: input.familyName, position };
+  }
+});
+
+export {
+  state_default
+};

package/dist/chunk-OEQUDML6.js

@@ -0,0 +1,80 @@
+import {
+  ColorReferenceSchema,
+  ColorValueSchema,
+  INDEX_TO_POSITION,
+  definePlugin,
+  external_exports
+} from "./chunk-WG6NCWQ2.js";
+
+// ../design-tokens/src/plugins/contrast.ts
+var ContrastInputSchema = external_exports.object({
+  familyColorValue: ColorValueSchema,
+  familyName: external_exports.string(),
+  basePosition: external_exports.number().int().min(0).max(10),
+  neutralFamilyName: external_exports.string().optional(),
+  neutralColorValue: ColorValueSchema.optional()
+});
+function findPartnerInPairs(pairs, basePosition) {
+  for (const [p1, p2] of pairs) {
+    if (p1 === basePosition) return p2;
+    if (p2 === basePosition) return p1;
+  }
+  return void 0;
+}
+var contrast_default = definePlugin({
+  id: "contrast",
+  input: ContrastInputSchema,
+  output: ColorReferenceSchema,
+  transform(input) {
+    const colorValue = input.familyColorValue;
+    if (colorValue.foregroundReferences?.auto) {
+      const ref = colorValue.foregroundReferences.auto;
+      return { family: ref.family, position: ref.position };
+    }
+    const basePosition = input.basePosition;
+    if (colorValue.accessibility) {
+      const wcagAAA = colorValue.accessibility.wcagAAA?.normal ?? [];
+      const wcagAA = colorValue.accessibility.wcagAA?.normal ?? [];
+      const contrastPosition = findPartnerInPairs(wcagAAA, basePosition) ?? findPartnerInPairs(wcagAA, basePosition);
+      if (contrastPosition !== void 0) {
+        return {
+          family: input.familyName,
+          position: INDEX_TO_POSITION[contrastPosition] ?? "500"
+        };
+      }
+    }
+    if (input.neutralFamilyName && input.neutralColorValue) {
+      const neutralValue = input.neutralColorValue;
+      if (neutralValue.accessibility?.onWhite?.aaa && neutralValue.accessibility.onWhite.aaa.length > 0) {
+        const bestPosition = neutralValue.accessibility.onWhite.aaa[0];
+        if (bestPosition !== void 0) {
+          return {
+            family: input.neutralFamilyName,
+            position: INDEX_TO_POSITION[bestPosition] ?? "500"
+          };
+        }
+      }
+      if (neutralValue.accessibility?.onWhite?.aa && neutralValue.accessibility.onWhite.aa.length > 0) {
+        const bestPosition = neutralValue.accessibility.onWhite.aa[0];
+        if (bestPosition !== void 0) {
+          return {
+            family: input.neutralFamilyName,
+            position: INDEX_TO_POSITION[bestPosition] ?? "500"
+          };
+        }
+      }
+      return {
+        family: input.neutralFamilyName,
+        position: basePosition <= 5 ? "900" : "100"
+      };
+    }
+    return {
+      family: input.familyName,
+      position: basePosition <= 5 ? "900" : "100"
+    };
+  }
+});
+
+export {
+  contrast_default
+};

package/dist/chunk-VV6WBGNC.js

@@ -0,0 +1,32 @@
+import {
+  ColorReferenceSchema,
+  ColorValueSchema,
+  INDEX_TO_POSITION,
+  definePlugin,
+  external_exports,
+  findDarkCounterpartIndex
+} from "./chunk-WG6NCWQ2.js";
+
+// ../design-tokens/src/plugins/invert.ts
+var InvertInputSchema = external_exports.object({
+  familyColorValue: ColorValueSchema,
+  familyName: external_exports.string(),
+  basePosition: external_exports.number().int().min(0).max(10)
+});
+var invert_default = definePlugin({
+  id: "invert",
+  input: InvertInputSchema,
+  output: ColorReferenceSchema,
+  transform(input) {
+    const darkIndex = findDarkCounterpartIndex(input.basePosition, input.familyColorValue);
+    const darkPosition = INDEX_TO_POSITION[darkIndex];
+    if (!darkPosition) {
+      throw new Error(`Invalid dark index ${darkIndex} for base position: ${input.basePosition}`);
+    }
+    return { family: input.familyName, position: darkPosition };
+  }
+});
+
+export {
+  invert_default
+};