@tonycodes-ui/mortar 0.0.0-stage → 0.12.0

package/cli/packet.mjs

@@ -0,0 +1,267 @@
+// Component contracts and build packets: everything an agent needs to compose
+// with a set of components, from the installed catalogue and docs.
+import { searchComponents, searchTemplates } from "./search.mjs";
+
+export const CSS_SETUP = `@import "tailwindcss";
+@import "@tonycodes-ui/mortar/styles.css";`;
+
+export const THEME_SETUP = `import { ThemeProvider } from "@tonycodes-ui/mortar";
+
+<ThemeProvider brand="neutral" density="comfortable" initialAppearance="system">
+  <App />
+</ThemeProvider>`;
+
+const importLine = (data, names) =>
+  `import { ${[...new Set(names)].sort().join(", ")} } from "${data.packageName}";`;
+
+/** The full contract of one component, as get_component returns it. */
+export function componentDetail(data, c, { example = true } = {}) {
+  const p = data.placement(c);
+  const props = Object.entries(c.contract.propTypes ?? {}).map(([name, t]) => ({
+    name,
+    type: t.type,
+    required: t.required,
+    ...(t.default !== undefined ? { default: t.default } : {}),
+    ...(c.contract.props?.[name] && c.contract.props[name] !== t.type
+      ? { description: c.contract.props[name] }
+      : {}),
+  }));
+  // Required props first; the sort is stable, so the rest keep their order.
+  props.sort((a, b) => Number(b.required) - Number(a.required));
+  const inherited = data.agent.inherited[c.export] !== undefined;
+  return {
+    name: c.export,
+    id: c.id,
+    version: c.version,
+    kit: p.kit,
+    kitTitle: p.kitTitle,
+    category: p.category ?? null,
+    categoryTitle: p.categoryTitle ?? null,
+    description: c.description,
+    import: importLine(data, [c.export]),
+    marker: `data-m-component="${c.export}"`,
+    props,
+    acceptsHtmlAttributes: inherited,
+    usage: c.contract.usage,
+    avoid: c.contract.avoid,
+    accessibility: c.contract.accessibility,
+    capabilities: c.capabilities,
+    dependencies: (c.contract.dependencies ?? [])
+      .map((id) => data.byId(id)?.export ?? id)
+      .sort(),
+    testing: c.testing,
+    templates: data.agent.templates
+      .filter((t) => t.components.includes(c.export))
+      .map((t) => t.id),
+    ...(example ? { example: data.agent.examples[c.export] ?? null } : {}),
+  };
+}
+
+/** Components and the catalogue components they render, transitively. */
+export function dependencyClosure(data, components) {
+  const requiredBy = new Map();
+  const queue = [...components];
+  const seen = new Set(components.map((c) => c.id));
+  while (queue.length) {
+    const c = queue.shift();
+    for (const id of c.contract.dependencies ?? []) {
+      const dep = data.byId(id);
+      if (!dep) continue;
+      if (!requiredBy.has(dep.export)) requiredBy.set(dep.export, new Set());
+      requiredBy.get(dep.export).add(c.export);
+      if (!seen.has(id)) {
+        seen.add(id);
+        queue.push(dep);
+      }
+    }
+  }
+  const requested = new Set(components.map((c) => c.export));
+  return [...requiredBy]
+    .filter(([name]) => !requested.has(name))
+    .map(([name, by]) => ({ name, requiredBy: [...by].sort() }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// What a brief is for, and the shared shell each purpose starts from
+// (principle shell-first).
+const PURPOSES = [
+  {
+    id: "auth",
+    words:
+      /\b(sign[\s-]?(in|up|on)|log[\s-]?(in|on)|login|register|registration|password|two[\s-]factor|2fa|mfa|otp|verify email)\b/i,
+    shell: "AuthLayout",
+    kit: "application",
+    guide: "auth-flows",
+    reason:
+      "AuthLayout is the page for every sign-in and registration step (docs/auth-flows.md).",
+  },
+  {
+    id: "ecommerce",
+    words:
+      /\b(shop|store|ecommerce|e-commerce|product|cart|basket|bag|checkout|order)s?\b/i,
+    shell: "MarketingHeader",
+    kit: "ecommerce",
+    reason:
+      "Storefront pages use the public-site chrome: MarketingHeader with Container and Footer, as the ecommerce templates do.",
+  },
+  {
+    id: "docs",
+    words:
+      /\b(docs|documentation|api reference|guide|knowledge base|help centre|help center|changelog)\b/i,
+    shell: "DocsShell",
+    kit: "docs",
+    reason: "DocsShell is the shared documentation shell.",
+  },
+  {
+    id: "marketing",
+    words:
+      /\b(landing|marketing|homepage|home page|website|public site|pricing page|about page|blog|launch|waitlist)\b/i,
+    shell: "MarketingHeader",
+    kit: "marketing",
+    reason:
+      "Public pages start from MarketingHeader (principle shell-first), with Footer.",
+  },
+  {
+    id: "application",
+    words:
+      /\b(app|application|dashboard|admin|console|portal|crm|settings|workspace|back[\s-]?office|internal tool|saas tool|inbox|account)\b/i,
+    shell: "AppShell",
+    kit: "application",
+    reason:
+      "Application screens start from AppShell (principle shell-first): navigation, page heading, content.",
+  },
+];
+
+/** Pick components for a free-text brief, with the reason for each. */
+export function chooseForBrief(data, brief) {
+  const purposes = PURPOSES.filter((p) => p.words.test(brief));
+  const kits = new Set(["foundation", ...purposes.map((p) => p.kit)]);
+  const chosen = new Map();
+  const choose = (name, reason) => {
+    const c = data.find(name);
+    if (!c) return;
+    if (!chosen.has(c.export))
+      chosen.set(c.export, { component: c, reasons: [] });
+    chosen.get(c.export).reasons.push(reason);
+  };
+  for (const p of purposes) choose(p.shell, p.reason);
+  if (purposes.some((p) => p.shell === "MarketingHeader"))
+    choose("Footer", "Public pages close with the shared Footer.");
+  let results = searchComponents(data, { query: brief, limit: 40 });
+  if (purposes.length)
+    results = results.map((r) => ({
+      ...r,
+      score: kits.has(r.kit) ? r.score : r.score / 2,
+    }));
+  results.sort((a, b) => b.score - a.score);
+  const top = results[0]?.score ?? 0;
+  for (const r of results.slice(0, 8))
+    if (r.score >= top * 0.6 && r.matched.length)
+      choose(r.name, `Matches “${r.matched.join("”, “")}” in the brief.`);
+  const templates = searchTemplates(data, brief, 3);
+  return { purposes, chosen: [...chosen.values()], templates };
+}
+
+/**
+ * A build packet for the named components, or for a brief. Unknown names are
+ * reported, not fatal.
+ */
+export function buildPacket(data, { components: names = [], brief } = {}) {
+  const unknown = [];
+  let selection = [];
+  let reasons = new Map();
+  let templates;
+  let purposes = [];
+  for (const n of names) {
+    const c = data.find(n);
+    if (c) selection.push(c);
+    else unknown.push(n);
+  }
+  if (brief) {
+    const picked = chooseForBrief(data, brief);
+    purposes = picked.purposes;
+    for (const { component, reasons: why } of picked.chosen) {
+      if (!selection.includes(component)) selection.push(component);
+      reasons.set(component.export, why);
+    }
+    templates = picked.templates;
+  }
+  selection = [...new Set(selection)];
+  const requested = new Set(selection.map((c) => c.export));
+  // Templates sharing the most components with the selection.
+  if (!templates || !templates.length)
+    templates = data.agent.templates
+      .map((t) => ({
+        ...t,
+        overlap: t.components.filter((n) => requested.has(n)).length,
+      }))
+      .filter((t) => t.overlap > 0)
+      .sort(
+        (a, b) =>
+          b.overlap / Math.sqrt(b.components.length) -
+          a.overlap / Math.sqrt(a.components.length),
+      )
+      .slice(0, 3);
+  const dependencies = dependencyClosure(data, selection);
+  const usesAuth = selection.some((c) => data.placement(c).category === "auth");
+  const guides = ["design", "conventions", "theming"];
+  if (usesAuth || purposes.some((p) => p.id === "auth"))
+    guides.push("auth-flows");
+  return {
+    package: data.packageName,
+    version: data.version,
+    ...(brief ? { brief } : {}),
+    ...(unknown.length
+      ? {
+          unknown: unknown.map((n) => ({
+            name: n,
+            suggestions: searchComponents(data, { query: n, limit: 3 }).map(
+              (r) => r.name,
+            ),
+          })),
+        }
+      : {}),
+    install: `npm install ${data.packageName} react react-dom tailwindcss`,
+    css: {
+      where: "Your app's Tailwind CSS entry (for example src/index.css).",
+      code: CSS_SETUP,
+      notes:
+        "Import Mortar after Tailwind. The package ships its compiled component styles, so no @source line is needed for Mortar itself. Do not override .m-* classes or [data-m-component] selectors; theme through tokens (get_guide theming).",
+    },
+    themeProvider: {
+      code: THEME_SETUP,
+      notes:
+        "Render one ThemeProvider at the app root. brand (neutral | green, or your own via brandTokens) and density (compact | comfortable | spacious) are controlled props; appearance changes through AppearanceControl. Pass navigate={(href) => router.push(href)} to route kit links through your router.",
+    },
+    import: importLine(data, ["ThemeProvider", ...requested]),
+    components: selection.map((c) => ({
+      ...componentDetail(data, c),
+      ...(reasons.has(c.export) ? { why: reasons.get(c.export) } : {}),
+    })),
+    dependencies: {
+      note: "Rendered inside the components above. They need no import unless you use them directly; they are listed so you know which contracts and states you inherit.",
+      components: dependencies,
+    },
+    templates: templates.map((t) => ({
+      id: t.id,
+      title: t.title,
+      description: t.description,
+      kind: t.kind,
+      components: t.components,
+      playground: `?recipe=${t.id}`,
+    })),
+    principles: data.principles.map((p, i) => ({
+      number: i + 1,
+      id: p.id,
+      instruction: p.instruction,
+    })),
+    conventions: data.guide("conventions"),
+    guides,
+    next: [
+      "Compose with named imports from the package; keep product names, data, routes and actions in props and slots.",
+      "Run `npx mortar audit` (or the audit_app tool) on the application and fix its findings.",
+      "Verify in a browser: mobile and desktop, light and dark, keyboard and focus, loading/empty/error states.",
+      "If a shared pattern is missing, contribute it to the kit through a GitHub pull request (get_guide contributing) instead of copying or overriding components.",
+    ],
+  };
+}

package/cli/search.mjs

@@ -0,0 +1,246 @@
+// Ranked, offline search over the catalogue: component names, kit and category,
+// descriptions, usage notes, capabilities and prop names.
+
+const STOP = new Set(
+  (
+    "a an and are as at be by for from has have i in into is it its of on or " +
+    "our the their this to use used using with we want need needs should " +
+    "mortar central semantic tokens component components ui page pages " +
+    "screen screens show shows build make some that which can my your " +
+    "where when what who will would like also each one all any"
+  ).split(" "),
+);
+
+// Everyday words for what the kit calls something else.
+const SYNONYMS = {
+  login: ["sign", "auth"],
+  logon: ["sign", "auth"],
+  signin: ["sign", "auth"],
+  signup: ["sign", "auth", "registration"],
+  register: ["sign", "registration", "auth"],
+  registration: ["sign", "auth"],
+  auth: ["sign", "authentication"],
+  authentication: ["sign", "auth"],
+  otp: ["code", "verification"],
+  verification: ["verify"],
+  verify: ["verification"],
+  "2fa": ["two", "factor", "code"],
+  mfa: ["two", "factor", "code"],
+  password: ["password", "auth"],
+  dashboard: ["application", "shell", "metric", "stat"],
+  admin: ["application", "shell"],
+  app: ["application", "shell"],
+  landing: ["marketing", "hero"],
+  homepage: ["marketing", "hero"],
+  website: ["marketing"],
+  modal: ["dialog", "overlay"],
+  popup: ["dialog", "overlay"],
+  drawer: ["slide", "over"],
+  sheet: ["slide", "over"],
+  dialog: ["modal", "overlay"],
+  menu: ["dropdown", "navigation"],
+  nav: ["navigation"],
+  navbar: ["navigation", "header"],
+  topbar: ["navbar", "header"],
+  sidenav: ["sidebar", "navigation"],
+  toast: ["notification"],
+  notification: ["toast", "notice"],
+  alert: ["notice", "banner", "callout"],
+  grid: ["table", "list"],
+  datagrid: ["table", "data"],
+  spreadsheet: ["table"],
+  kpi: ["metric", "stat"],
+  stats: ["stat", "metric"],
+  analytics: ["metric", "stat", "chart"],
+  shop: ["ecommerce", "product"],
+  store: ["ecommerce", "product"],
+  basket: ["cart", "bag"],
+  bag: ["cart"],
+  docs: ["documentation"],
+  documentation: ["docs"],
+  plans: ["pricing", "plan"],
+  plan: ["pricing"],
+  faq: ["question"],
+  questions: ["faq"],
+  testimonials: ["testimonial", "social"],
+  reviews: ["review", "testimonial"],
+  tooltip: ["popover"],
+  toggle: ["switch"],
+  spinner: ["loading", "progress"],
+  loader: ["loading", "progress"],
+  wizard: ["steps", "progress"],
+  stepper: ["steps", "progress"],
+  upload: ["attachment", "file"],
+  files: ["attachment"],
+  chat: ["chat", "comment"],
+  comments: ["comment", "activity"],
+  timeline: ["activity", "feed"],
+  schedule: ["calendar"],
+  events: ["calendar"],
+  search: ["search", "command", "combobox"],
+  theme: ["theme", "appearance", "brand"],
+  darkmode: ["appearance", "theme"],
+  avatar: ["avatar", "person"],
+  profile: ["avatar", "description"],
+  team: ["team", "people"],
+};
+
+const stem = (word) =>
+  word.length > 4 && word.endsWith("ies")
+    ? word.slice(0, -3) + "y"
+    : word.length > 3 && word.endsWith("s") && !word.endsWith("ss")
+      ? word.slice(0, -1)
+      : word;
+
+/** Lower-case terms: camelCase split, punctuation removed, stop words dropped. */
+export function terms(text) {
+  return String(text ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w && !STOP.has(w))
+    .map(stem);
+}
+
+/** Query terms with their weights: typed terms 1, synonyms 0.5. */
+function queryTerms(query) {
+  const raw = String(query ?? "").toLowerCase();
+  const out = new Map();
+  const add = (t, w) => {
+    t = stem(t);
+    if (!STOP.has(t)) out.set(t, Math.max(out.get(t) ?? 0, w));
+  };
+  // "sign in", "log in", "sign-up" and "two-factor" read as one idea.
+  const joined = raw
+    .replace(/\blog[\s-]?(in|on)\b/g, "login")
+    .replace(/\bsign[\s-]?in\b/g, "signin sign")
+    .replace(/\bsign[\s-]?up\b/g, "signup sign");
+  for (const t of terms(joined)) {
+    add(t, 1);
+    for (const s of SYNONYMS[t] ?? []) add(s, 0.5);
+  }
+  return out;
+}
+
+const FIELDS = [
+  ["name", 6],
+  ["category", 3],
+  ["kit", 2],
+  ["description", 2],
+  ["usage", 1],
+  ["capabilities", 1],
+  ["props", 0.5],
+];
+
+function documentFor(data, c) {
+  const p = data.placement(c);
+  const doc = {
+    name: terms(c.export),
+    category: terms(`${p.categoryTitle ?? ""} ${p.category ?? ""}`),
+    kit: terms(`${p.kitTitle} ${p.kit}`),
+    description: terms(c.description),
+    usage: terms(`${c.contract.usage ?? ""} ${c.contract.accessibility ?? ""}`),
+    capabilities: terms((c.capabilities ?? []).join(" ")),
+    props: terms(Object.keys(c.contract.propTypes ?? {}).join(" ")),
+  };
+  return Object.fromEntries(
+    Object.entries(doc).map(([k, v]) => [k, new Set(v)]),
+  );
+}
+
+const cache = new WeakMap();
+
+function score(doc, query) {
+  let total = 0;
+  const matched = [];
+  for (const [term, weight] of query) {
+    let best = 0;
+    for (const [field, w] of FIELDS) {
+      const set = doc[field];
+      let hit = set.has(term) ? w : 0;
+      if (!hit && term.length >= 4)
+        for (const word of set)
+          if (word.length > term.length && word.startsWith(term)) {
+            hit = w * 0.6;
+            break;
+          }
+      best = Math.max(best, hit);
+    }
+    if (best) {
+      total += best * weight;
+      if (weight === 1) matched.push(term);
+    }
+  }
+  return { total, matched };
+}
+
+/**
+ * Components ranked for a query. Optional kit and category filters accept ids
+ * or titles. Each result: name, kit, category, description, capabilities, score.
+ */
+export function searchComponents(
+  data,
+  { query = "", kit, category, limit = 10 } = {},
+) {
+  let docs = cache.get(data);
+  if (!docs) {
+    docs = new Map(data.components.map((c) => [c, documentFor(data, c)]));
+    cache.set(data, docs);
+  }
+  const q = queryTerms(query);
+  const exact = data.find(String(query).replace(/\s+/g, ""));
+  const norm = (s) => String(s ?? "").toLowerCase();
+  const results = [];
+  for (const c of data.components) {
+    const p = data.placement(c);
+    if (kit && ![p.kit, p.kitTitle].map(norm).includes(norm(kit))) continue;
+    if (
+      category &&
+      ![p.category, p.categoryTitle].map(norm).includes(norm(category))
+    )
+      continue;
+    let { total, matched } = q.size
+      ? score(docs.get(c), q)
+      : { total: 1, matched: [] };
+    if (c === exact) total += 100;
+    // Every typed term in the name: "sign in panel" → SignInPanel.
+    const typed = [...q].filter(([, w]) => w === 1).map(([t]) => t);
+    if (typed.length && typed.every((t) => docs.get(c).name.has(t))) total += 4;
+    // Shell-first: a page shell ranks above the parts it holds.
+    if (total && p.category === "shells") total += 1;
+    if (total > 0)
+      results.push({
+        name: c.export,
+        kit: p.kit,
+        category: p.categoryTitle ?? null,
+        description: c.description,
+        capabilities: c.capabilities,
+        score: Math.round(total * 10) / 10,
+        matched,
+      });
+  }
+  results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return results.slice(0, Math.max(1, Math.min(Number(limit) || 10, 115)));
+}
+
+/** Page templates ranked for a query (title, description, kind and components). */
+export function searchTemplates(data, query, limit = 3) {
+  const q = queryTerms(query);
+  const out = [];
+  for (const t of data.agent.templates) {
+    const doc = {
+      name: new Set([...terms(`${t.id} ${t.title}`), t.id.replace(/-/g, "")]),
+      category: new Set(terms(t.kind)),
+      kit: new Set(),
+      description: new Set(terms(t.description)),
+      usage: new Set(terms(t.components.join(" "))),
+      capabilities: new Set(),
+      props: new Set(),
+    };
+    const { total } = score(doc, q);
+    if (total > 0) out.push({ ...t, score: Math.round(total * 10) / 10 });
+  }
+  out.sort((a, b) => b.score - a.score);
+  return out.slice(0, limit);
+}