ds-tis 1.0.0-beta.10

package/js/theme/semantic-mapper.js

@@ -0,0 +1,138 @@
+/* ============================================================
+   semantic-mapper.js — ThemeConfig → CSS custom properties
+
+   Espelha os aliases de tokens/semantic/light.json e dark.json:
+     light: brand.bg = brand.600/700/800, links = 700/800, focus = 600
+     dark:  brand.bg = brand.400/500/400, links = 400/300/200, focus = 500
+
+   Produz três grupos de variáveis:
+     1. Foundation brand scale  (--ds-color-brand-50..950)
+     2. Overlays toned          (--ds-overlay-brand-600 e brand-400)
+     3. Semantic com contraste  (--ds-brand-content-*, focus, etc.)
+     4. Radius + tipografia
+   ============================================================ */
+
+import { generateBrandScale, scaleFromExplicit, STEPS } from './palette.js';
+import { generateTonedOverlays } from './overlay.js';
+import { pickAccessibleForeground, WCAG_AA_UI } from './contrast.js';
+import { generateRadiusTheme } from './radius.js';
+import { buildFontStacks } from './typography.js';
+
+/** Neutros do DS usados como foreground candidatos (foundation.color.neutral). */
+const NEUTRAL_LIGHT = '#F8FAFC'; // neutral-50
+const NEUTRAL_DARK = '#0F172A'; // neutral-900
+
+/**
+ * Gera o mapa completo de CSS vars (sem `--` de seletor) para um modo.
+ *
+ * @param {object} config - ThemeConfig normalizado.
+ * @param {'light'|'dark'} mode
+ * @returns {{ vars: Record<string,string>, contrast: object }}
+ */
+export function mapThemeToVars(config, mode) {
+  const scale = config.brand?.scale
+    ? { ...generateBrandScale(config.brand.seed), ...scaleFromExplicit(config.brand.scale) }
+    : generateBrandScale(config.brand.seed, { chromaBoost: config.brand?.chromaBoost ?? 1 });
+
+  const vars = {};
+
+  // 1. Foundation brand scale
+  for (const step of STEPS) {
+    vars[`--ds-color-brand-${step}`] = scale[step];
+  }
+
+  // 2. Overlays toned (light usa 600; dark usa 400)
+  const light = generateTonedOverlays(scale[600], 'light');
+  const dark = generateTonedOverlays(scale[400], 'dark');
+  vars['--ds-overlay-brand-600-12'] = light.default;
+  vars['--ds-overlay-brand-600-20'] = light.hover;
+  vars['--ds-overlay-brand-600-28'] = light.active;
+  vars['--ds-overlay-brand-400-15'] = dark.default;
+  vars['--ds-overlay-brand-400-25'] = dark.hover;
+  vars['--ds-overlay-brand-400-32'] = dark.active;
+
+  // 3. Semantic brand/toned/link/focus — espelha tokens/semantic/{light,dark}.json
+  // e o patch documentado em docs/theming.html (ex.: Sunset).
+  let brandFill;
+  let fg;
+
+  if (mode === 'dark') {
+    brandFill = scale[400];
+    fg = pickAccessibleForeground(brandFill, {
+      light: NEUTRAL_LIGHT,
+      dark: NEUTRAL_DARK,
+      threshold: WCAG_AA_UI,
+    });
+    vars['--ds-brand-background-default'] = scale[400];
+    vars['--ds-brand-background-hover'] = scale[500];
+    vars['--ds-brand-background-active'] = scale[400];
+    vars['--ds-brand-content-default'] = fg.fg;
+    vars['--ds-brand-content-hover'] = fg.fg;
+    vars['--ds-toned-background-default'] = dark.default;
+    vars['--ds-toned-background-hover'] = dark.hover;
+    vars['--ds-toned-background-active'] = dark.active;
+    vars['--ds-toned-content-default'] = scale[400];
+    vars['--ds-link-content-default'] = scale[400];
+    vars['--ds-link-content-hover'] = scale[300];
+    vars['--ds-link-content-active'] = scale[200];
+    vars['--ds-content-brand'] = scale[400];
+    vars['--ds-border-focus'] = scale[500];
+    vars['--ds-border-brand'] = scale[500];
+    vars['--ds-focus-ring-color'] = scale[500];
+  } else {
+    brandFill = scale[600];
+    fg = pickAccessibleForeground(brandFill, {
+      light: NEUTRAL_LIGHT,
+      dark: NEUTRAL_DARK,
+      threshold: WCAG_AA_UI,
+    });
+    vars['--ds-brand-background-default'] = scale[600];
+    vars['--ds-brand-background-hover'] = scale[700];
+    vars['--ds-brand-background-active'] = scale[800];
+    vars['--ds-brand-content-default'] = fg.fg;
+    vars['--ds-brand-content-hover'] = fg.fg;
+    vars['--ds-toned-background-default'] = light.default;
+    vars['--ds-toned-background-hover'] = light.hover;
+    vars['--ds-toned-background-active'] = light.active;
+    vars['--ds-toned-content-default'] = scale[700];
+    vars['--ds-link-content-default'] = scale[700];
+    vars['--ds-link-content-hover'] = scale[800];
+    vars['--ds-link-content-active'] = scale[800];
+    vars['--ds-content-brand'] = scale[700];
+    vars['--ds-border-focus'] = scale[600];
+    vars['--ds-border-brand'] = scale[600];
+    vars['--ds-focus-ring-color'] = scale[600];
+  }
+
+  // 4. Radius + tipografia (mode-invariant, mas emitimos em ambos)
+  if (config.radius != null) {
+    const { foundation, semantic, component } = generateRadiusTheme(config.radius);
+    for (const [step, value] of Object.entries(foundation)) {
+      vars[`--ds-radius-${step}`] = value;
+    }
+    if (semantic) {
+      for (const [slot, value] of Object.entries(semantic)) {
+        vars[`--ds-radius-${slot}`] = value;
+      }
+    }
+    for (const [name, value] of Object.entries(component)) {
+      vars[name] = value;
+    }
+  }
+  if (config.typography) {
+    const stacks = buildFontStacks(config.typography);
+    vars['--ds-font-family-sans'] = stacks.sans;
+    vars['--ds-font-family-mono'] = stacks.mono;
+    vars['--ds-font-family-display'] = stacks.display;
+  }
+
+  return {
+    vars,
+    contrast: {
+      brandFill,
+      foreground: fg.fg,
+      ratio: fg.ratio,
+      passes: fg.passes,
+    },
+  };
+}

package/js/theme/typography.js

@@ -0,0 +1,33 @@
+/* ============================================================
+   typography.js — monta font stacks preservando fallbacks do DS
+
+   O customizer troca a fonte principal (sans/mono/display) mas mantém
+   a cadeia de fallback do sistema, para não perder robustez quando a
+   webfont escolhida não carregar.
+   ============================================================ */
+
+const SANS_FALLBACK =
+  "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif";
+const MONO_FALLBACK =
+  "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace";
+
+/** Envolve o nome da família em aspas se tiver espaço. */
+function quoteFamily(name) {
+  const n = String(name).trim();
+  if (!n) return '';
+  return /\s/.test(n) && !/^['"]/.test(n) ? `'${n}'` : n;
+}
+
+/**
+ * @param {object} cfg
+ * @param {string} [cfg.sans] - família principal (ex "Inter").
+ * @param {string} [cfg.mono] - família mono (ex "DM Mono").
+ * @param {string} [cfg.display] - família de display (default: = sans).
+ * @returns {{sans:string, mono:string, display:string}} stacks CSS.
+ */
+export function buildFontStacks({ sans = 'Inter', mono = 'DM Mono', display } = {}) {
+  const sansStack = `${quoteFamily(sans)}, ${SANS_FALLBACK}`;
+  const monoStack = `${quoteFamily(mono)}, ${MONO_FALLBACK}`;
+  const displayStack = `${quoteFamily(display || sans)}, ${SANS_FALLBACK}`;
+  return { sans: sansStack, mono: monoStack, display: displayStack };
+}

package/js/theme/url-state.js

@@ -0,0 +1,52 @@
+/* ============================================================
+   url-state.js — encode/decode do ThemeConfig na query string
+
+   Permite compartilhar presets por link (como ?preset=... do shadcn).
+   Usa base64url de um JSON compacto. Funciona em browser e Node
+   (usa btoa/atob quando existem, Buffer como fallback).
+   ============================================================ */
+
+import { normalizeConfig } from './config-schema.js';
+
+function b64encode(str) {
+  if (typeof btoa === 'function') return btoa(unescape(encodeURIComponent(str)));
+  return Buffer.from(str, 'utf-8').toString('base64');
+}
+function b64decode(str) {
+  if (typeof atob === 'function') return decodeURIComponent(escape(atob(str)));
+  return Buffer.from(str, 'base64').toString('utf-8');
+}
+function toUrlSafe(b64) {
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromUrlSafe(s) {
+  let b64 = s.replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4) b64 += '=';
+  return b64;
+}
+
+/** ThemeConfig → token base64url compacto. */
+export function encodeConfig(config) {
+  const cfg = normalizeConfig(config);
+  const compact = {
+    b: cfg.brand.seed,
+    cb: cfg.brand.chromaBoost ?? 1,
+    r: cfg.radius,
+    fs: cfg.typography.sans,
+    fm: cfg.typography.mono,
+    m: cfg.mode,
+  };
+  return toUrlSafe(b64encode(JSON.stringify(compact)));
+}
+
+/** token base64url → ThemeConfig normalizado. Lança em token inválido. */
+export function decodeConfig(token) {
+  const json = b64decode(fromUrlSafe(token));
+  const c = JSON.parse(json);
+  return normalizeConfig({
+    brand: { seed: c.b, chromaBoost: c.cb },
+    radius: c.r,
+    typography: { sans: c.fs, mono: c.fm },
+    mode: c.m,
+  });
+}

package/js/tooltip.js

@@ -0,0 +1,227 @@
+/* ============================================================
+   tooltip.js — runtime público para Tooltip (required)
+
+   Anatomia e estados visuais: css/components/tooltip.css
+   Uso:
+     <div class="ds-tooltip ds-tooltip--top">
+       <button type="button" aria-describedby="tip-1">…</button>
+       <span class="ds-tooltip__content" id="tip-1" role="tooltip">…</span>
+     </div>
+
+   Ciclo de vida:
+     const instances = initTooltips(root);
+     destroyTooltips(root); // ou instance.destroy()
+
+   WCAG 1.4.13: dismissible (Escape), hoverable (pointer no content),
+   persistent enquanto hover/focus ativo.
+   ============================================================ */
+
+const instances = new Set();
+const SHOW_DELAY_MS = 100;
+const HIDE_DELAY_MS = 100;
+let generatedId = 0;
+
+function emit(root, name, detail) {
+  root.dispatchEvent(new CustomEvent(name, { bubbles: true, detail }));
+}
+
+function getTrigger(root, content) {
+  return [...root.children].find((child) => child !== content) || null;
+}
+
+function createInstance(root) {
+  const content = root.querySelector(':scope > .ds-tooltip__content[role="tooltip"], :scope > .ds-tooltip__content');
+  if (!content) return null;
+  if (!content.hasAttribute('role')) content.setAttribute('role', 'tooltip');
+
+  const trigger = getTrigger(root, content);
+  if (!trigger) return null;
+
+  if (!content.id) {
+    do {
+      generatedId += 1;
+      content.id = `ds-tooltip-${generatedId}`;
+    } while (content.ownerDocument.getElementById(content.id) !== content);
+  }
+
+  const describedBy = (trigger.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
+  if (!describedBy.includes(content.id)) {
+    trigger.setAttribute('aria-describedby', [...describedBy, content.id].join(' '));
+  }
+
+  const cleanups = [];
+  const on = (target, type, handler, options) => {
+    target.addEventListener(type, handler, options);
+    cleanups.push(() => target.removeEventListener(type, handler, options));
+  };
+
+  let showTimer = null;
+  let hideTimer = null;
+  let focusFrame = null;
+  let open = root.dataset.open === 'true';
+  let suppressUntilLeave = false;
+  const view = root.ownerDocument.defaultView;
+
+  const clearTimers = () => {
+    if (showTimer) {
+      clearTimeout(showTimer);
+      showTimer = null;
+    }
+    if (hideTimer) {
+      clearTimeout(hideTimer);
+      hideTimer = null;
+    }
+    if (focusFrame) {
+      view.cancelAnimationFrame(focusFrame);
+      focusFrame = null;
+    }
+  };
+
+  const inst = {
+    root,
+    show() {
+      clearTimers();
+      if (suppressUntilLeave || open) return;
+      open = true;
+      root.dataset.open = 'true';
+      content.removeAttribute('hidden');
+      emit(root, 'ds-tooltip-show', { root, trigger, content });
+    },
+    hide() {
+      clearTimers();
+      if (!open) return;
+      open = false;
+      delete root.dataset.open;
+      content.setAttribute('hidden', '');
+      emit(root, 'ds-tooltip-hide', { root, trigger, content });
+    },
+    scheduleShow() {
+      clearTimers();
+      if (suppressUntilLeave || open) return;
+      showTimer = setTimeout(() => {
+        showTimer = null;
+        inst.show();
+      }, SHOW_DELAY_MS);
+    },
+    scheduleHide() {
+      clearTimers();
+      if (!open) return;
+      hideTimer = setTimeout(() => {
+        hideTimer = null;
+        if (root.contains(root.ownerDocument.activeElement)) return;
+        inst.hide();
+      }, HIDE_DELAY_MS);
+    },
+    destroy() {
+      clearTimers();
+      if (open) {
+        open = false;
+        delete root.dataset.open;
+        content.setAttribute('hidden', '');
+      }
+      while (cleanups.length) cleanups.pop()();
+      delete root.dataset.dsTooltipInit;
+      instances.delete(inst);
+    },
+  };
+
+  // Start closed unless the markup already requests open (static docs demos).
+  if (root.dataset.open === 'true') {
+    open = true;
+    content.removeAttribute('hidden');
+  } else {
+    open = false;
+    content.setAttribute('hidden', '');
+  }
+
+  on(root, 'pointerenter', () => {
+    suppressUntilLeave = false;
+    inst.scheduleShow();
+  });
+  on(root, 'pointerleave', () => {
+    suppressUntilLeave = false;
+    inst.scheduleHide();
+  });
+
+  on(trigger, 'focusin', () => {
+    if (!suppressUntilLeave) inst.show();
+  });
+  on(trigger, 'focusout', () => {
+    if (focusFrame) view.cancelAnimationFrame(focusFrame);
+    focusFrame = view.requestAnimationFrame(() => {
+      focusFrame = null;
+      if (!instances.has(inst)) return;
+      if (root.contains(root.ownerDocument.activeElement)) return;
+      suppressUntilLeave = false;
+      inst.scheduleHide();
+    });
+  });
+
+  on(root.ownerDocument, 'keydown', (e) => {
+    if (!open) return;
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      suppressUntilLeave = true;
+      inst.hide();
+    }
+  });
+
+  return inst;
+}
+
+function isInside(root, node) {
+  return root === document || root === node || (typeof root.contains === 'function' && root.contains(node));
+}
+
+/**
+ * @param {ParentNode} [root]
+ */
+export function initTooltips(root = document) {
+  const created = [];
+  const tooltips = [];
+
+  if (root instanceof Element && root.matches('.ds-tooltip')) tooltips.push(root);
+  if (typeof root.querySelectorAll === 'function') {
+    tooltips.push(...root.querySelectorAll('.ds-tooltip'));
+  }
+
+  tooltips.forEach((tooltip) => {
+    if (tooltip.dataset.dsTooltipInit === 'true') return;
+    if (tooltip.closest('[inert]')) return;
+    const inst = createInstance(tooltip);
+    if (inst) {
+      tooltip.dataset.dsTooltipInit = 'true';
+      instances.add(inst);
+      created.push(inst);
+    }
+  });
+
+  return created;
+}
+
+/**
+ * @param {ParentNode} [root]
+ */
+export function destroyTooltips(root = document) {
+  for (const inst of [...instances]) {
+    if (isInside(root, inst.root)) inst.destroy();
+  }
+}
+
+/**
+ * @param {HTMLElement} root
+ */
+export function showTooltip(root) {
+  const inst = [...instances].find((item) => item.root === root);
+  inst?.show();
+  return inst;
+}
+
+/**
+ * @param {HTMLElement} root
+ */
+export function hideTooltip(root) {
+  const inst = [...instances].find((item) => item.root === root);
+  inst?.hide();
+  return inst;
+}

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "ds-tis",
+  "version": "1.0.0-beta.10",
+  "description": "White-label CSS design system with DTCG tokens, component contracts, and light/dark mode",
+  "homepage": "https://tis-experience.github.io/ds-tis/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tis-experience/ds-tis.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tis-experience/ds-tis/issues"
+  },
+  "main": "css/design-system.css",
+  "style": "css/design-system.css",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": "./css/design-system.css",
+    "./css": "./css/design-system.css",
+    "./css/design-system.css": "./css/design-system.css",
+    "./accordion": "./js/accordion.js",
+    "./accordion.js": "./js/accordion.js",
+    "./combobox": "./js/combobox.js",
+    "./combobox.js": "./js/combobox.js",
+    "./modal": "./js/modal.js",
+    "./modal.js": "./js/modal.js",
+    "./menu": "./js/menu.js",
+    "./menu.js": "./js/menu.js",
+    "./tabs": "./js/tabs.js",
+    "./tabs.js": "./js/tabs.js",
+    "./tooltip": "./js/tooltip.js",
+    "./tooltip.js": "./js/tooltip.js",
+    "./theme": "./js/theme/index.js",
+    "./theme/*": "./js/theme/*.js",
+    "./metadata": "./docs/api/consumer-context.json",
+    "./metadata/components": "./docs/api/components.json",
+    "./metadata/tokens": "./docs/api/tokens.json",
+    "./metadata/foundations": "./docs/api/foundations.json",
+    "./metadata/adrs": "./docs/api/adrs.json",
+    "./agent-guide": "./docs/agent-consumer-usage.md",
+    "./agent-guide/en": "./docs/agent-consumer-usage.en.md",
+    "./llms": "./docs/llms.txt",
+    "./llms-full": "./docs/llms-full.txt",
+    "./templates/*": "./docs/templates/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "css/",
+    "docs/agent-consumer-usage.md",
+    "docs/agent-consumer-usage.en.md",
+    "docs/api/adrs.json",
+    "docs/api/components.json",
+    "docs/api/consumer-context.json",
+    "docs/api/foundations.json",
+    "docs/api/tokens.json",
+    "docs/llms.txt",
+    "docs/llms-full.txt",
+    "docs/templates/",
+    "js/accordion.js",
+    "js/combobox.js",
+    "js/menu.js",
+    "js/modal.js",
+    "js/tabs.js",
+    "js/tooltip.js",
+    "js/package.json",
+    "js/theme/"
+  ],
+  "keywords": [
+    "design-system",
+    "css",
+    "tokens",
+    "white-label",
+    "dark-mode"
+  ],
+  "author": "TIS Experience Engineering",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build:tokens": "node build-tokens.mjs",
+    "sync:docs": "node scripts/sync-docs.mjs",
+    "verify:tokens": "node scripts/tokens-verify.mjs",
+    "build:api": "node scripts/build-api.mjs",
+    "build:icons": "node scripts/build-icons.mjs",
+    "build:llms": "node scripts/build-llms.mjs",
+    "build:all": "npm run build:tokens && npm run build:icons && npm run sync:docs && npm run build:api && npm run build:llms && npm run verify:tokens && npm test",
+    "prepublishOnly": "npm run build:all && npm run test:app-ready -- --release",
+    "pack:check": "npm pack --dry-run && npm run test:audit-scenarios && npm run test:app-ready",
+    "test": "node scripts/test-token-integrity.mjs && node scripts/test-css-references.mjs && node scripts/test-generators.mjs && node scripts/test-docs-consumption.mjs && node scripts/test-accordion-docs.mjs && node scripts/test-combobox-docs.mjs && node scripts/test-pagination-docs.mjs && node scripts/test-field-docs.mjs && node scripts/test-interactive.mjs && node scripts/test-api-runtime.mjs && node scripts/test-consumer-context.mjs && node scripts/test-readiness-evidence.mjs && node scripts/test-component-readiness.mjs && node scripts/test-runtime-lifecycle.mjs && node scripts/test-theme-engine.mjs && node scripts/test-a11y.mjs && npm run test:a11y:theme-playground",
+    "test:app-ready": "node scripts/test-app-ready.mjs",
+    "test:audit-scenarios": "node scripts/test-audit-scenarios.mjs",
+    "test:audit-scenarios:ci": "node scripts/test-audit-scenarios.mjs --skip-local-figma",
+    "test:consumer-smoke": "node scripts/test-consumer-smoke.mjs",
+    "test:docs-consumption": "node scripts/test-docs-consumption.mjs",
+    "test:runtime-lifecycle": "node scripts/test-runtime-lifecycle.mjs",
+    "test:self": "node scripts/test-self.mjs",
+    "test:readiness": "node scripts/test-component-readiness.mjs",
+    "test:readiness:evidence": "node scripts/test-readiness-evidence.mjs",
+    "test:theme": "node scripts/test-theme-engine.mjs",
+    "test:a11y": "node scripts/test-a11y.mjs",
+    "test:a11y:theme-playground": "node scripts/test-a11y.mjs --strict-load --server --filter theme-playground --zero-blocking",
+    "test:visual": "node scripts/test-visual.mjs",
+    "test:visual:update": "node scripts/test-visual.mjs --update",
+    "sync:tokens-from-figma": "node scripts/sync-tokens-from-figma.mjs",
+    "sync:tokens-from-figma:write": "node scripts/sync-tokens-from-figma.mjs --write",
+    "build:registry": "node scripts/build-token-registry.mjs",
+    "build:registry:init": "node scripts/build-token-registry.mjs --init",
+    "verify:registry": "node scripts/build-token-registry.mjs --check",
+    "security:check": "node scripts/security-check.mjs",
+    "figma:plugin:check": "node --check figma-plugin/snapshot-exporter/code.js",
+    "figma:snapshot:install": "node scripts/install-figma-snapshot.mjs",
+    "figma:snapshot:refresh": "node scripts/refresh-figma-snapshot.mjs",
+    "verify:figma-structure": "node scripts/verify-figma-structure.mjs",
+    "audit:component-tokens": "node scripts/verify-figma-structure.mjs --strict-unused",
+    "agent:preflight": "node scripts/agent-preflight.mjs",
+    "verify:agent-docs": "node scripts/verify-agent-docs.mjs",
+    "agents:create-run": "node scripts/agents/create-run.mjs",
+    "agents:validate-run": "node scripts/agents/validate-run.mjs",
+    "agents:next-step": "node scripts/agents/next-step.mjs",
+    "agents:gate": "node scripts/agents/gate.mjs",
+    "agents:validate-matrix": "node scripts/agents/validate-matrix.mjs"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.2",
+    "@tokens-studio/sd-transforms": "^2.0.3",
+    "lucide": "^1.18.0",
+    "marked": "^18.0.2",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.59.1",
+    "pngjs": "^7.0.0",
+    "style-dictionary": "^5.4.0"
+  }
+}