@clidey/dory 1.0.3 → 1.0.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clidey/dory",
   "private": false,
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "A CLI tool for building and previewing documentation sites",
   "keywords": [
@@ -43,17 +43,18 @@
     "build:embed:loader": "vite build -c vite.config.embed-loader.ts",
     "build:embed:widget": "vite build -c vite.config.embed-widget.ts",
     "preview": "vite preview",
-    "test": "vitest run",
+    "test": "node scripts/check-trigger-children.mjs src && vitest run",
+    "lint:triggers": "node scripts/check-trigger-children.mjs src",
     "publish": "npm run build && npm publish --access public --no-git-checks",
     "prepublishOnly": "echo 'Skipping prepublishOnly - build handled by publish script'"
   },
   "dependencies": {
     "@algolia/autocomplete-core": "1.19.9",
-    "@clidey/ux": "1.2.3",
-    "@fortawesome/fontawesome-svg-core": "7.3.0",
-    "@fortawesome/free-brands-svg-icons": "7.3.0",
-    "@fortawesome/free-regular-svg-icons": "7.3.0",
-    "@fortawesome/free-solid-svg-icons": "7.3.0",
+    "@clidey/ux": "1.5.1",
+    "@fortawesome/fontawesome-svg-core": "7.3.1",
+    "@fortawesome/free-brands-svg-icons": "7.3.1",
+    "@fortawesome/free-regular-svg-icons": "7.3.1",
+    "@fortawesome/free-solid-svg-icons": "7.3.1",
     "@fortawesome/react-fontawesome": "3.4.0",
     "@headlessui/react": "2.2.10",
     "@heroicons/react": "2.2.0",
@@ -65,11 +66,11 @@
     "classnames": "2.5.1",
     "flexsearch": "0.8.212",
     "gray-matter": "4.0.3",
-    "katex": "0.17.0",
+    "katex": "0.18.3",
     "lucide-react": "1.24.0",
-    "mermaid": "11.16.0",
+    "mermaid": "11.16.1",
     "motion": "12.42.2",
-    "preact": "10.29.7",
+    "preact": "10.29.8",
     "preact-render-to-string": "6.7.0",
     "prism-react-renderer": "2.4.1",
     "react-highlight-words": "0.21.0",
@@ -88,7 +89,8 @@
   "devDependencies": {
     "@types/node": "26.1.1",
     "@types/react-highlight-words": "0.20.1",
-    "vitest": "4.1.10"
+    "@typescript/typescript6": "6.0.2",
+    "vitest": "5.0.4"
   },
   "pnpm": {
     "overrides": {
@@ -96,4 +98,4 @@
       "react-redux": "9.3.0"
     }
   }
-}
+}

package/scripts/check-trigger-children.mjs

@@ -0,0 +1,60 @@
+// Lint guard: fail when a @clidey/ux trigger has `asChild` and its child cannot be slotted.
+//
+//   node scripts/check-trigger-children.mjs <dir> [<dir>...]
+//
+// Fails on `<XTrigger asChild>` whose child is a fragment, string literal,
+// array, conditional expression, multiple children, or a component on the
+// deny list in trigger-children.json. Deny-listed children fail even without
+// `asChild`, since wrapping them is never what the author meant.
+
+import {
+  asChildAttribute,
+  childSlotStatus,
+  classifyChildren,
+  forEachTrigger,
+  listTsxFiles,
+  location,
+  parse,
+  tagName,
+} from './trigger-children-lib.mjs';
+
+const dirs = process.argv.slice(2).filter((arg) => !arg.startsWith('--'));
+if (dirs.length === 0) {
+  console.error('usage: check-trigger-children.mjs <dir> [<dir>...]');
+  process.exit(2);
+}
+
+const errors = [];
+let triggers = 0;
+
+for (const dir of dirs) {
+  for (const file of listTsxFiles(dir)) {
+    const source = parse(file);
+    forEachTrigger(source, (element, imports) => {
+      triggers += 1;
+      const trigger = tagName(element);
+      const asChild = asChildAttribute(element);
+      const where = location(source, element);
+      const shape = classifyChildren(element);
+
+      if (shape.kind === 'element') {
+        if (childSlotStatus(shape.child, imports) === 'denied') {
+          errors.push(`${where} <${trigger}> wraps ${tagName(shape.child)}, which does not forward refs or spread props; wrap it in a <span>`);
+        }
+        return;
+      }
+      if (!asChild || asChild.value === false) return;
+      // A bare identifier (`{node}`) may hold an element; the library validates it at runtime.
+      if (shape.kind === 'expression') return;
+      errors.push(`${where} <${trigger} asChild> child is ${shape.kind}; asChild needs exactly one element child`);
+    });
+  }
+}
+
+if (errors.length > 0) {
+  console.error(`check-trigger-children: ${errors.length} problem(s) in ${triggers} trigger(s)`);
+  for (const line of errors) console.error(`  ${line}`);
+  console.error('See @clidey/ux docs/triggers-and-aschild.md.');
+  process.exit(1);
+}
+console.log(`check-trigger-children: ${triggers} trigger(s) OK`);

package/scripts/trigger-children-lib.mjs

@@ -0,0 +1,149 @@
+// Shared AST helpers for codemod-trigger-aschild.mjs and check-trigger-children.mjs.
+// Uses the TypeScript compiler API already installed for the frontend build.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(path.join(here, '..', 'package.json'));
+
+function loadTypeScript() {
+  // TypeScript 7 ships a native compiler whose npm package has no JS compiler API
+  // (or only a stub); fall back to the @typescript/typescript6 compatibility package.
+  let candidate;
+  try {
+    candidate = require('typescript');
+  } catch {
+    candidate = undefined;
+  }
+  if (candidate && typeof candidate.createSourceFile === 'function') return candidate;
+  return require('@typescript/typescript6');
+}
+
+/** @type {import('typescript')} */
+export const ts = loadTypeScript();
+
+export const config = JSON.parse(fs.readFileSync(path.join(here, 'trigger-children.json'), 'utf8'));
+
+const TRIGGERS = new Set(config.triggers);
+const INFERRED_UX = new Set(config.inferredUxChildren);
+const INFERRED_INTRINSICS = new Set(config.inferredIntrinsics);
+const DENY = new Set(config.denyList);
+
+/** Recursively lists .tsx files under `dir`, skipping generated and dependency folders. */
+export function listTsxFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'generated' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listTsxFiles(full));
+    else if (entry.name.endsWith('.tsx')) out.push(full);
+  }
+  return out;
+}
+
+export function parse(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+
+/** Maps local identifier → module specifier for every import in the file. */
+export function importSources(source) {
+  const map = new Map();
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement) || !statement.importClause) continue;
+    const from = statement.moduleSpecifier.text;
+    const { name, namedBindings } = statement.importClause;
+    if (name) map.set(name.text, from);
+    if (namedBindings && ts.isNamedImports(namedBindings)) {
+      for (const element of namedBindings.elements) map.set(element.name.text, from);
+    }
+  }
+  return map;
+}
+
+export function tagName(node) {
+  const name = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName;
+  return name.getText();
+}
+
+function isMeaningfulChild(child) {
+  if (ts.isJsxText(child)) return child.text.trim().length > 0;
+  if (ts.isJsxExpression(child)) return child.expression !== undefined;
+  return true;
+}
+
+/** Classifies the children of a trigger element. */
+export function classifyChildren(element) {
+  const children = element.children.filter(isMeaningfulChild);
+  if (children.length === 0) return { kind: 'empty', children };
+  if (children.length > 1) return { kind: 'multiple', children };
+  const [child] = children;
+  if (ts.isJsxText(child)) return { kind: 'text', children, child };
+  if (ts.isJsxFragment(child)) return { kind: 'fragment', children, child };
+  if (ts.isJsxExpression(child)) {
+    const expr = child.expression;
+    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr) || ts.isTemplateExpression(expr)) {
+      return { kind: 'text', children, child };
+    }
+    if (ts.isConditionalExpression(expr) || ts.isBinaryExpression(expr)) return { kind: 'conditional', children, child };
+    if (ts.isArrayLiteralExpression(expr)) return { kind: 'array', children, child };
+    if (ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr)) return { kind: 'element', children, child: expr };
+    if (ts.isParenthesizedExpression(expr) && (ts.isJsxElement(expr.expression) || ts.isJsxSelfClosingElement(expr.expression))) {
+      return { kind: 'element', children, child: expr.expression };
+    }
+    return { kind: 'expression', children, child };
+  }
+  if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) return { kind: 'element', children, child };
+  return { kind: 'expression', children, child };
+}
+
+/** Returns the `asChild` attribute node and its literal value (true/false/undefined for non-literal). */
+export function asChildAttribute(element) {
+  const attributes = element.openingElement.attributes.properties;
+  for (const attr of attributes) {
+    if (!ts.isJsxAttribute(attr) || attr.name.getText() !== 'asChild') continue;
+    if (!attr.initializer) return { attr, value: true };
+    if (ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
+      const expr = attr.initializer.expression;
+      if (expr.kind === ts.SyntaxKind.TrueKeyword) return { attr, value: true };
+      if (expr.kind === ts.SyntaxKind.FalseKeyword) return { attr, value: false };
+    }
+    return { attr, value: undefined };
+  }
+  return null;
+}
+
+/**
+ * Decides how the library will treat a child element:
+ * 'inferred' (slot-safe, asChild implied), 'denied' (never slot-safe), or 'unknown'.
+ */
+export function childSlotStatus(childElement, imports) {
+  const name = tagName(childElement);
+  if (name.includes('.')) return 'unknown';
+  if (/^[a-z]/.test(name)) return INFERRED_INTRINSICS.has(name) ? 'inferred' : 'unknown';
+  const from = imports.get(name);
+  if (from !== config.uxPackage) return 'unknown';
+  if (INFERRED_UX.has(name)) return 'inferred';
+  if (DENY.has(name)) return 'denied';
+  return 'unknown';
+}
+
+/** Visits every `<XTrigger>...</XTrigger>` element in the file. */
+export function forEachTrigger(source, visit) {
+  const imports = importSources(source);
+  const walk = (node) => {
+    if (ts.isJsxElement(node) && TRIGGERS.has(tagName(node))) {
+      visit(node, imports);
+    }
+    ts.forEachChild(node, walk);
+  };
+  walk(source);
+}
+
+export function location(source, node) {
+  const { line, character } = source.getLineAndCharacterOfPosition(node.getStart());
+  return `${path.relative(process.cwd(), source.fileName)}:${line + 1}:${character + 1}`;
+}

package/scripts/trigger-children.json

@@ -0,0 +1,47 @@
+{
+  "$comment": "Shared by codemod-trigger-aschild.mjs and check-trigger-children.mjs. Mirrors the slottable markers in @clidey/ux src/lib/slot.ts.",
+  "triggers": [
+    "DropdownMenuTrigger",
+    "TooltipTrigger",
+    "PopoverTrigger",
+    "DialogTrigger",
+    "SheetTrigger",
+    "AlertDialogTrigger",
+    "DrawerTrigger",
+    "ContextMenuTrigger"
+  ],
+  "uxPackage": "@clidey/ux",
+  "inferredUxChildren": [
+    "Button",
+    "Badge",
+    "BreadcrumbLink",
+    "ButtonGroupText",
+    "Kbd",
+    "SidebarMenuButton",
+    "SidebarMenuAction",
+    "SidebarMenuSubButton",
+    "DropdownMenuTrigger",
+    "TooltipTrigger",
+    "PopoverTrigger",
+    "DialogTrigger",
+    "SheetTrigger",
+    "AlertDialogTrigger",
+    "DrawerTrigger",
+    "ContextMenuTrigger"
+  ],
+  "inferredIntrinsics": ["button", "a", "div", "span", "input", "label", "li"],
+  "denyList": [
+    "CopyButton",
+    "ConfirmDialog",
+    "FormSheet",
+    "MultiSearchSelect",
+    "Tree",
+    "ChartContainer",
+    "MapContainer",
+    "MasterDetailPanels",
+    "ResizablePanelGroup",
+    "ResizablePanel",
+    "ResizableHandle",
+    "Toaster"
+  ]
+}