inkhouse 0.1.0-beta.0

package/src/config.ts

@@ -0,0 +1,115 @@
+// Figma Plugin API types are provided by the runtime
+
+import type { TokenSourceMode } from './token-source';
+
+export interface ProjectConfig {
+  owner: string;
+  repo: string;
+  baseBranch: string;
+  tokenPath: string;
+  tokenSourceMode: TokenSourceMode;
+  cssTokenPath: string;
+  syncDtcgOnPush: boolean;
+  allowNewTokensFromFigma: boolean;
+  newTokenPrefixes: string[];
+  projectName: string;
+}
+
+// Default GitHub configuration (can be overridden via Settings)
+export const DEFAULT_CONFIG: ProjectConfig = {
+  owner: '',
+  repo: '',
+  baseBranch: 'main',
+  tokenPath: 'design-tokens/tokens.dtcg.json',
+  tokenSourceMode: 'auto',
+  cssTokenPath: '',
+  syncDtcgOnPush: false,
+  allowNewTokensFromFigma: false,
+  newTokenPrefixes: [],
+  projectName: 'My Project',
+};
+
+// Runtime config - loaded from storage
+export let GITHUB_CONFIG: ProjectConfig | null = null;
+
+function normalizeTokenPath(tokenPath: unknown): string {
+  if (typeof tokenPath !== 'string' || !tokenPath.trim()) {
+    return DEFAULT_CONFIG.tokenPath;
+  }
+  if (tokenPath === 'design-tokens/tokens.json') {
+    return DEFAULT_CONFIG.tokenPath;
+  }
+  return tokenPath;
+}
+
+function normalizeTokenSourceMode(mode: unknown): TokenSourceMode {
+  if (mode === 'css' || mode === 'dtcg' || mode === 'auto') return mode;
+  return 'auto';
+}
+
+function normalizeCssTokenPath(cssTokenPath: unknown): string {
+  if (typeof cssTokenPath !== 'string') return '';
+  return cssTokenPath.trim();
+}
+
+function normalizeSyncDtcgOnPush(syncDtcgOnPush: unknown): boolean {
+  return syncDtcgOnPush === true;
+}
+
+function normalizeAllowNewTokensFromFigma(value: unknown): boolean {
+  return value === true;
+}
+
+function normalizeNewTokenPrefixes(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => String(entry || '').trim())
+      .filter((entry) => entry.length > 0);
+  }
+  if (typeof value === 'string') {
+    return value
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0);
+  }
+  return [];
+}
+
+// Load config from storage or use defaults
+export async function loadConfig(): Promise<ProjectConfig> {
+  if (GITHUB_CONFIG) return GITHUB_CONFIG;
+  try {
+    const stored = await figma.clientStorage.getAsync('project_config');
+    if (stored && typeof stored === 'object') {
+      const storedConfig = stored as Partial<ProjectConfig>;
+      GITHUB_CONFIG = {
+        ...DEFAULT_CONFIG,
+        ...storedConfig,
+        tokenPath: normalizeTokenPath(storedConfig.tokenPath),
+        tokenSourceMode: normalizeTokenSourceMode(storedConfig.tokenSourceMode),
+        cssTokenPath: normalizeCssTokenPath(storedConfig.cssTokenPath),
+        syncDtcgOnPush: normalizeSyncDtcgOnPush(storedConfig.syncDtcgOnPush),
+        allowNewTokensFromFigma: normalizeAllowNewTokensFromFigma((storedConfig as any).allowNewTokensFromFigma),
+        newTokenPrefixes: normalizeNewTokenPrefixes((storedConfig as any).newTokenPrefixes),
+      };
+      // Persist one-time migrations so old installs stop carrying stale settings.
+      await figma.clientStorage.setAsync('project_config', GITHUB_CONFIG);
+    } else {
+      GITHUB_CONFIG = Object.assign({}, DEFAULT_CONFIG);
+    }
+  } catch (e) {
+    GITHUB_CONFIG = Object.assign({}, DEFAULT_CONFIG);
+  }
+  return GITHUB_CONFIG;
+}
+
+export async function saveConfig(config: ProjectConfig): Promise<void> {
+  config.tokenPath = normalizeTokenPath(config.tokenPath);
+  config.tokenSourceMode = normalizeTokenSourceMode((config as any).tokenSourceMode);
+  config.cssTokenPath = normalizeCssTokenPath((config as any).cssTokenPath);
+  config.syncDtcgOnPush = normalizeSyncDtcgOnPush((config as any).syncDtcgOnPush);
+  (config as any).allowNewTokensFromFigma = normalizeAllowNewTokensFromFigma((config as any).allowNewTokensFromFigma);
+  (config as any).newTokenPrefixes = normalizeNewTokenPrefixes((config as any).newTokenPrefixes);
+  GITHUB_CONFIG = config;
+  await figma.clientStorage.setAsync('project_config', config);
+}

package/src/design-system.ts

@@ -0,0 +1,59 @@
+// Design System Page Generation
+// Orchestrates building the full design system preview page in Figma.
+
+import { debug } from './colors';
+import { getThemeNames, TOKENS } from './tokens';
+import { demoFrameColors, demoFrameRadii } from './variables';
+import { createUIComponents } from './ui-builder';
+
+/**
+ * Build a single "Design System" page containing tokens preview and all UI components.
+ * Clears any existing content on the page before rebuilding.
+ */
+export function buildDesignSystemSinglePage(): void {
+  let ds: any = (figma.root as any).children.find((p: any) => p.name === 'Design System');
+  if (!ds) { ds = figma.createPage(); ds.name = 'Design System'; }
+  figma.currentPage = ds;
+  const nodes = Array.from(ds.children || []);
+  for (const n of nodes as any[]) n.remove();
+
+  const tokensRow = figma.createFrame();
+  tokensRow.name = 'Design Tokens';
+  tokensRow.layoutMode = 'HORIZONTAL';
+  tokensRow.primaryAxisSizingMode = 'AUTO';
+  tokensRow.counterAxisSizingMode = 'AUTO';
+  tokensRow.itemSpacing = 32;
+  tokensRow.paddingLeft = tokensRow.paddingRight = 32;
+  tokensRow.paddingTop = tokensRow.paddingBottom = 24;
+  tokensRow.fills = [];
+  tokensRow.strokes = [];
+  const themeNames = getThemeNames(TOKENS);
+  for (const themeName of themeNames) {
+    tokensRow.appendChild(demoFrameColors(themeName));
+  }
+  tokensRow.appendChild(demoFrameRadii());
+  tokensRow.x = 48;
+  tokensRow.y = 48;
+  ds.appendChild(tokensRow);
+  debug('Tokens row', { columns: tokensRow.children.length, height: tokensRow.height });
+
+  // Scanner names components after their file (capitalised, dashes kept): gradient-showcase.tsx → 'Gradient-showcase'
+  const EFFECTS_COMPONENTS = ['Gradient-showcase'];
+
+  const offset = tokensRow.y + tokensRow.height + 80;
+  const uiSection = createUIComponents(ds, {
+    themeNames,
+    yOffset: offset,
+    xOffset: 48,
+    excludeComponents: EFFECTS_COMPONENTS,
+  });
+
+  const effectsOffset = offset + (uiSection ? uiSection.height : 0) + 80;
+  createUIComponents(ds, {
+    themeNames,
+    yOffset: effectsOffset,
+    xOffset: 48,
+    sectionTitle: 'Effects',
+    onlyComponents: EFFECTS_COMPONENTS,
+  });
+}

package/src/dev-server.ts

@@ -0,0 +1,173 @@
+// --- Dev Server Integration ---
+// Fetching is done via UI iframe (code.js sandbox has no network access).
+// Architecture:
+//   1. code.js shows UI (visible or hidden)
+//   2. UI iframe loads and sends 'ui-ready'
+//   3. code.js sends 'fetch-component-defs' request
+//   4. UI fetches from localhost dev server
+//   5. UI sends 'component-defs-result' back to code.js
+
+import { debug } from './colors';
+
+interface ComponentDefsResult {
+  requestId: string;
+  data: ComponentDefs | null;
+}
+
+interface ComponentDefs {
+  components: unknown[];
+  [key: string]: unknown;
+}
+
+// Pending fetch callbacks keyed by requestId
+let _pendingFetchCallbacks: Record<string, (data: ComponentDefs | null) => void> = {};
+let _fetchRequestCounter = 0;
+let _uiReady = false;
+let _uiReadyCallbacks: Array<() => void> = [];
+
+/**
+ * Wait for UI iframe to be ready (sends 'ui-ready' on load)
+ */
+export function waitForUIReady(): Promise<void> {
+  if (_uiReady) return Promise.resolve();
+  return new Promise<void>(function (resolve) {
+    _uiReadyCallbacks.push(resolve);
+    // Safety timeout - if UI never sends ready, resolve anyway after 500ms
+    setTimeout(function () {
+      resolve();
+    }, 500);
+  });
+}
+
+/**
+ * Handle UI ready signal
+ */
+export function handleUIReady(): void {
+  _uiReady = true;
+  for (let i = 0; i < _uiReadyCallbacks.length; i++) {
+    _uiReadyCallbacks[i]();
+  }
+  _uiReadyCallbacks = [];
+}
+
+/**
+ * Fetch component definitions from dev server via UI iframe.
+ * The UI iframe has network access; code.js sandbox does not.
+ * Returns a Promise that resolves with the data or null.
+ */
+export async function fetchComponentDefsFromServer(): Promise<ComponentDefs | null> {
+  // Ensure UI is loaded and ready to receive messages
+  await waitForUIReady();
+
+  return new Promise<ComponentDefs | null>(function (resolve) {
+    const requestId = 'fetch-' + ++_fetchRequestCounter;
+    _pendingFetchCallbacks[requestId] = resolve;
+
+    debug('Sending fetch request to UI: ' + requestId);
+    figma.ui.postMessage({ type: 'fetch-component-defs', requestId: requestId });
+
+    // Timeout after 10s
+    setTimeout(function () {
+      if (_pendingFetchCallbacks[requestId]) {
+        delete _pendingFetchCallbacks[requestId];
+        debug('Fetch timed out');
+        resolve(null);
+      }
+    }, 10000);
+  });
+}
+
+// Pending image fetch callbacks keyed by requestId
+type ImageFetchResult = { bytes: number[] | null; svgText: string | null };
+const _pendingImageCallbacks: Record<string, (result: ImageFetchResult) => void> = {};
+let _imageRequestCounter = 0;
+
+/**
+ * Handle image fetch result from UI iframe
+ */
+export function handleImageResult(msg: { requestId: string; bytes: number[] | null; svgText?: string | null }): void {
+  const cb = _pendingImageCallbacks[msg.requestId];
+  if (cb) {
+    delete _pendingImageCallbacks[msg.requestId];
+    cb({ bytes: msg.bytes, svgText: msg.svgText ?? null });
+  }
+}
+
+function fetchImageData(url: string): Promise<ImageFetchResult> {
+  return new Promise<ImageFetchResult>(function (resolve) {
+    const requestId = 'img-' + ++_imageRequestCounter;
+    _pendingImageCallbacks[requestId] = resolve;
+    figma.ui.postMessage({ type: 'fetch-image', url, requestId });
+    // Short timeout — CORS failures reject immediately; slow servers get 3s
+    setTimeout(function () {
+      if (_pendingImageCallbacks[requestId]) {
+        delete _pendingImageCallbacks[requestId];
+        resolve({ bytes: null, svgText: null });
+      }
+    }, 3000);
+  });
+}
+
+export type PrefetchResult = { hashMap: Map<string, string>; svgMap: Map<string, string> };
+
+/**
+ * Pre-fetch a set of image srcs via the UI iframe (which has network access).
+ * Relative paths are resolved against localhost on the given port.
+ * Fetches all images in parallel. SVGs are stored as raw strings (for createNodeFromSvg);
+ * raster images are stored as figma imageHash fills.
+ */
+export async function prefetchImages(
+  srcs: string[],
+  port: number | string
+): Promise<PrefetchResult> {
+  await waitForUIReady();
+  const hashMap = new Map<string, string>();
+  const svgMap = new Map<string, string>();
+  const unique = [...new Set(srcs.filter(Boolean))];
+
+  const entries = await Promise.all(
+    unique.map(async (src) => {
+      const url = src.startsWith('http') ? src : `http://localhost:${port}${src}`;
+      const data = await fetchImageData(url);
+      return { src, ...data };
+    })
+  );
+
+  for (const { src, bytes, svgText } of entries) {
+    if (svgText) {
+      svgMap.set(src, svgText);
+    } else if (bytes && bytes.length > 0) {
+      try {
+        const img = (figma as any).createImage(new Uint8Array(bytes));
+        hashMap.set(src, img.hash);
+      } catch (_e) { /* ignore */ }
+    }
+  }
+  return { hashMap, svgMap };
+}
+
+/**
+ * Handle fetch result from UI iframe
+ */
+export function handleComponentDefsResult(msg: ComponentDefsResult): void {
+  const cb = _pendingFetchCallbacks[msg.requestId];
+  if (cb) {
+    delete _pendingFetchCallbacks[msg.requestId];
+    debug('Received component defs from UI, data: ' + (msg.data ? 'yes' : 'null'));
+    cb(msg.data);
+  }
+}
+
+/**
+ * Update COMPONENT_DEFS with fresh data from server.
+ * Returns { success: boolean, data: ComponentDefs | null } so the caller
+ * (main.ts) can assign the data to COMPONENT_DEFS.
+ */
+export async function refreshComponentDefs(): Promise<{ success: boolean; data: ComponentDefs | null }> {
+  const freshDefs = await fetchComponentDefsFromServer();
+  if (freshDefs && freshDefs.components && freshDefs.components.length > 0) {
+    debug('Loaded ' + freshDefs.components.length + ' components from dev server');
+    return { success: true, data: freshDefs };
+  }
+  return { success: false, data: null };
+}

package/src/figma-globals.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="@figma/plugin-typings" />
+
+declare const __html__: string;

package/src/font-style-resolver.ts

@@ -0,0 +1,171 @@
+declare const figma: any;
+
+type FontStyleIndex = Record<string, string[]>;
+
+let AVAILABLE_STYLES_BY_FAMILY: FontStyleIndex | null = null;
+let INIT_PROMISE: Promise<void> | null = null;
+
+function normalizeStyleToken(style: string): string {
+  return String(style || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+function parseExplicitNumericWeight(style: string): number | null {
+  const normalized = normalizeStyleToken(style);
+  const match = normalized.match(/\b([1-9]00)\b/);
+  if (!match) return null;
+  const n = parseInt(match[1], 10);
+  if (!Number.isFinite(n)) return null;
+  return n;
+}
+
+export function inferFontWeight(style: string): number {
+  const explicit = parseExplicitNumericWeight(style);
+  if (explicit != null) return explicit;
+  const normalized = normalizeStyleToken(style);
+  if (!normalized) return 400;
+  if (/\bthin\b/.test(normalized)) return 100;
+  if (/\b(extra|ultra)\s*light\b/.test(normalized)) return 200;
+  if (/\blight\b/.test(normalized)) return 300;
+  if (/\b(book)\b/.test(normalized)) return 350;
+  if (/\b(normal|regular|roman)\b/.test(normalized)) return 400;
+  if (/\bmedium\b/.test(normalized)) return 500;
+  if (/\b(semi|demi)\s*bold\b/.test(normalized)) return 600;
+  if (/\bbold\b/.test(normalized) && !/\b(extra|ultra)\s*bold\b/.test(normalized)) return 700;
+  if (/\b(extra|ultra|heavy)\s*bold\b/.test(normalized) || /\bheavy\b/.test(normalized)) return 800;
+  if (/\bblack\b/.test(normalized)) return 900;
+  return 400;
+}
+
+function inferItalic(style: string): boolean {
+  const normalized = normalizeStyleToken(style);
+  return /\b(italic|oblique)\b/.test(normalized);
+}
+
+function uniquePush(target: string[], value: string): void {
+  for (let i = 0; i < target.length; i++) {
+    if (target[i] === value) return;
+  }
+  target.push(value);
+}
+
+export function rankStylesForRequest(availableStyles: string[], requestedStyle: string): string[] {
+  const ranked: Array<{ style: string; score: number; styleWeight: number }> = [];
+  const requestWeight = inferFontWeight(requestedStyle);
+  const requestItalic = inferItalic(requestedStyle);
+  const requestToken = normalizeStyleToken(requestedStyle);
+
+  for (let i = 0; i < availableStyles.length; i++) {
+    const style = availableStyles[i];
+    const styleWeight = inferFontWeight(style);
+    const styleItalic = inferItalic(style);
+    const styleToken = normalizeStyleToken(style);
+    let score = Math.abs(styleWeight - requestWeight);
+    if (styleItalic !== requestItalic) score += 120;
+    if (styleToken === requestToken) score -= 30;
+    if (styleToken.indexOf(requestToken) !== -1 && requestToken) score -= 10;
+    ranked.push({ style: style, score: score, styleWeight: styleWeight });
+  }
+
+  ranked.sort((a, b) => {
+    if (a.score !== b.score) return a.score - b.score;
+    if (a.styleWeight !== b.styleWeight) {
+      // For medium+ requests, prefer heavier fallback on exact distance ties.
+      // This avoids picking Regular over SemiBold for font-medium when 500 isn't available.
+      if (requestWeight >= 500) return b.styleWeight - a.styleWeight;
+      return a.styleWeight - b.styleWeight;
+    }
+    return a.style.localeCompare(b.style);
+  });
+
+  const out: string[] = [];
+  for (let i = 0; i < ranked.length; i++) {
+    uniquePush(out, ranked[i].style);
+  }
+  return out;
+}
+
+function buildFallbackCandidates(requestedStyle: string): string[] {
+  const normalized = normalizeStyleToken(requestedStyle);
+  if (normalized === 'medium') return ['Medium', 'SemiBold', 'Semibold', 'DemiBold', 'Regular'];
+  if (normalized === 'semibold' || normalized === 'semi bold' || normalized === 'demibold' || normalized === 'demi bold') {
+    return ['SemiBold', 'Semibold', 'DemiBold', 'Bold', 'Medium', 'Regular'];
+  }
+  if (normalized === 'bold') return ['Bold', 'SemiBold', 'Semibold', 'Medium', 'Regular'];
+  if (normalized === 'regular' || normalized === 'normal') return ['Regular', 'Book', 'Roman', 'Normal'];
+  const out: string[] = [];
+  if (requestedStyle) out.push(requestedStyle);
+  out.push('Regular');
+  return out;
+}
+
+function isWidthAxisVariant(style: string): boolean {
+  const normalized = normalizeStyleToken(style);
+  return /\b(condensed|narrow|compressed|expanded|extended)\b/.test(normalized);
+}
+
+function requestAsksForWidthAxis(requestedStyle: string): boolean {
+  return isWidthAxisVariant(requestedStyle);
+}
+
+export async function initializeFontStyleIndex(): Promise<void> {
+  if (AVAILABLE_STYLES_BY_FAMILY != null) return;
+  if (INIT_PROMISE) {
+    await INIT_PROMISE;
+    return;
+  }
+  INIT_PROMISE = (async () => {
+    const next: FontStyleIndex = {};
+    try {
+      const fonts = await figma.listAvailableFontsAsync();
+      for (let i = 0; i < fonts.length; i++) {
+        const entry = fonts[i];
+        const family = entry.fontName.family;
+        const style = entry.fontName.style;
+        if (!family || !style) continue;
+        if (!next[family]) next[family] = [];
+        uniquePush(next[family], style);
+      }
+      AVAILABLE_STYLES_BY_FAMILY = next;
+    } catch (_err) {
+      AVAILABLE_STYLES_BY_FAMILY = {};
+    }
+  })();
+  await INIT_PROMISE;
+}
+
+export function getKnownStylesForFamily(family: string): string[] {
+  if (AVAILABLE_STYLES_BY_FAMILY == null) return [];
+  const styles = AVAILABLE_STYLES_BY_FAMILY[family];
+  if (!styles) return [];
+  return styles.slice();
+}
+
+export function getFontStyleCandidatesForFamily(family: string, requestedStyle: string): string[] {
+  const out: string[] = [];
+  const styles = getKnownStylesForFamily(family);
+  if (styles.length > 0) {
+    if (requestedStyle) uniquePush(out, requestedStyle);
+    const wantsWidthAxis = requestAsksForWidthAxis(requestedStyle);
+    const preferredPool = wantsWidthAxis
+      ? styles
+      : styles.filter(style => !isWidthAxisVariant(style));
+    const rankedPreferred = rankStylesForRequest(preferredPool.length > 0 ? preferredPool : styles, requestedStyle);
+    for (let i = 0; i < rankedPreferred.length; i++) uniquePush(out, rankedPreferred[i]);
+    // Keep width-axis variants as late fallback when not explicitly requested.
+    if (!wantsWidthAxis) {
+      const rankedAll = rankStylesForRequest(styles, requestedStyle);
+      for (let i = 0; i < rankedAll.length; i++) uniquePush(out, rankedAll[i]);
+    }
+    // Keep generic aliases as a final fallback, never before ranked known styles.
+    const fallback = buildFallbackCandidates(requestedStyle);
+    for (let i = 0; i < fallback.length; i++) uniquePush(out, fallback[i]);
+  } else {
+    const fallback = buildFallbackCandidates(requestedStyle);
+    for (let i = 0; i < fallback.length; i++) uniquePush(out, fallback[i]);
+  }
+  if (out.length === 0) out.push('Regular');
+  return out;
+}