@flanksource/clicky-ui 0.3.6 → 0.3.8

package/oxlint-plugins/clicky-ui-shared.js

@@ -0,0 +1,132 @@
+// Shared AST helpers for the `clicky-ui` oxlint plugin (see ./clicky-ui.js).
+// Kept free of rule-specific logic so each predicate can be unit-tested in
+// isolation (clicky-ui.test.ts).
+
+/** Returns the string value of a string `Literal` node, else undefined. */
+export function literalString(node) {
+  if (node && node.type === "Literal" && typeof node.value === "string") {
+    return node.value;
+  }
+  return undefined;
+}
+
+/**
+ * Returns the numeric value of a numeric `Literal` (incl. a unary `-` prefix,
+ * e.g. `-1`), else undefined. Used to detect hardcoded `zIndex`/spacing values.
+ */
+export function numericLiteral(node) {
+  if (node && node.type === "Literal" && typeof node.value === "number") {
+    return node.value;
+  }
+  if (
+    node &&
+    node.type === "UnaryExpression" &&
+    node.operator === "-" &&
+    node.argument?.type === "Literal" &&
+    typeof node.argument.value === "number"
+  ) {
+    return -node.argument.value;
+  }
+  return undefined;
+}
+
+/** Name of a JSX attribute (`className`, `style`, `role`, …) or undefined. */
+export function attributeName(node) {
+  return node?.name?.name;
+}
+
+/** Name of an intrinsic (lowercase) JSX element, else undefined. */
+export function intrinsicElementName(opening) {
+  const name = opening?.name;
+  if (name?.type !== "JSXIdentifier") return undefined;
+  const text = name.name;
+  // Intrinsic DOM elements are lowercase; components are PascalCase.
+  return typeof text === "string" && /^[a-z]/.test(text) ? text : undefined;
+}
+
+/**
+ * Recursively collect every static string reachable from a JSX attribute value
+ * — handles `"a b"`, `{`a ${x}`}`, and `{cn("a", cond && "b")}` so className
+ * token rules see the same tokens regardless of how they are composed.
+ */
+export function collectStrings(node, out = []) {
+  if (!node) return out;
+  switch (node.type) {
+    case "Literal":
+      if (typeof node.value === "string") out.push(node.value);
+      break;
+    case "JSXExpressionContainer":
+      collectStrings(node.expression, out);
+      break;
+    case "TemplateLiteral":
+      for (const quasi of node.quasis) out.push(quasi.value.cooked ?? quasi.value.raw);
+      break;
+    case "CallExpression":
+      for (const arg of node.arguments) collectStrings(arg, out);
+      break;
+    case "ArrayExpression":
+      for (const el of node.elements) collectStrings(el, out);
+      break;
+    case "ObjectExpression":
+      // clsx/cn object form: keys are the class names.
+      for (const prop of node.properties) {
+        if (prop.type === "Property") {
+          if (prop.key?.type === "Literal") collectStrings(prop.key, out);
+          else if (prop.key?.type === "Identifier") out.push(prop.key.name);
+        }
+      }
+      break;
+    case "LogicalExpression":
+      collectStrings(node.left, out);
+      collectStrings(node.right, out);
+      break;
+    case "ConditionalExpression":
+      collectStrings(node.consequent, out);
+      collectStrings(node.alternate, out);
+      break;
+    default:
+      break;
+  }
+  return out;
+}
+
+/** Split collected className strings into individual class tokens. */
+export function classTokens(strings) {
+  const tokens = [];
+  for (const str of strings) {
+    for (const token of str.split(/\s+/)) {
+      if (token) tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+/** The object literal passed to a `style={{…}}` attribute, else undefined. */
+export function styleObject(attribute) {
+  const value = attribute?.value;
+  if (value?.type !== "JSXExpressionContainer") return undefined;
+  const expr = value.expression;
+  return expr?.type === "ObjectExpression" ? expr : undefined;
+}
+
+/** Static property key (`color`, `zIndex`, …) of an object Property, else undefined. */
+export function propertyKey(prop) {
+  if (prop?.type !== "Property" || prop.computed) return undefined;
+  if (prop.key?.type === "Identifier") return prop.key.name;
+  if (prop.key?.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+  return undefined;
+}
+
+// Known iconify icon-set prefixes used in this codebase. An allowlist (rather
+// than a generic `a:b` match) so non-icon namespaced strings aren't flagged.
+const ICON_SET_PREFIXES = ["ph", "lucide", "codicon", "tabler", "mdi", "svg-spinners"];
+// `jb-expui-<category>` (nodes, general, actions, json, status, toolwindows,
+// breakpoints, run, …) — JetBrains expui sets, whose prefix carries hyphens.
+const ICONIFY_NAME = new RegExp(
+  `^(?:${ICON_SET_PREFIXES.join("|")}|jb-expui-[a-z]+):[a-z0-9][a-z0-9-]*$`,
+);
+
+/** True when a string is a known icon-set name (e.g. "codicon:clock"). */
+export function isIconifyName(value) {
+  return typeof value === "string" && ICONIFY_NAME.test(value);
+}

package/oxlint-plugins/clicky-ui.js

@@ -0,0 +1,34 @@
+// The `clicky-ui` oxlint plugin — guardrails for projects that consume
+// @flanksource/clicky-ui. Reference it from a downstream `.oxlintrc.json`:
+//
+//   {
+//     "jsPlugins": [
+//       { "name": "clicky-ui", "specifier": "@flanksource/clicky-ui/oxlint-plugins" }
+//     ],
+//     "rules": {
+//       "clicky-ui/prefer-clicky-components": "warn",
+//       "clicky-ui/no-adhoc-overlay": "error",
+//       "clicky-ui/prefer-tailwind-classes": "warn",
+//       "clicky-ui/prefer-theme-tokens": "error",
+//       "clicky-ui/prefer-clicky-icons": "warn"
+//     }
+//   }
+//
+// See packages/ui/oxlint-plugins/README.md for the full guide.
+
+import preferClickyComponents from "./clicky-ui-prefer-components.js";
+import noAdhocOverlay from "./clicky-ui-no-adhoc-overlay.js";
+import preferTailwindClasses from "./clicky-ui-prefer-tailwind.js";
+import preferThemeTokens from "./clicky-ui-prefer-theme.js";
+import preferClickyIcons from "./clicky-ui-prefer-icons.js";
+
+export default {
+  meta: { name: "clicky-ui" },
+  rules: {
+    "prefer-clicky-components": preferClickyComponents,
+    "no-adhoc-overlay": noAdhocOverlay,
+    "prefer-tailwind-classes": preferTailwindClasses,
+    "prefer-theme-tokens": preferThemeTokens,
+    "prefer-clicky-icons": preferClickyIcons,
+  },
+};

package/oxlint-plugins/no-iconify-names.js

@@ -0,0 +1,37 @@
+// Custom OxLint rule: disallow iconify-style icon name strings (e.g. "lucide:maximize-2")
+// anywhere in clicky-ui source — as a value, argument, or prop. Icons must be imported as
+// generated components and passed via the `icon` prop. The `name` fallback prop on <Icon>
+// exists only for external consumers of the published library. The generated icon pipeline
+// (src/icons/components/** and scripts/build-icons.ts), which legitimately maps these names,
+// is exempted via config; stories/tests are exempted via .oxlintrc overrides.
+
+import { isIconifyName } from "./clicky-ui-shared.js";
+
+function message(value) {
+  return (
+    `Iconify-style icon name "${value}" is not allowed in clicky-ui source. ` +
+    "Import the generated icon component from \"../icons\" (e.g. UiFullscreen) and pass it " +
+    "via the `icon` prop."
+  );
+}
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow iconify-style icon name strings in clicky-ui source" },
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (isIconifyName(node.value)) {
+          context.report({ message: message(node.value), node });
+        }
+      },
+    };
+  },
+};
+
+export default {
+  meta: { name: "clicky-icons" },
+  rules: { "no-iconify-names": rule },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flanksource/clicky-ui",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Flanksource Clicky UI — React component library built on shadcn/ui with light/dark and density theming.",
   "homepage": "https://github.com/flanksource/clicky-ui#readme",
   "bugs": "https://github.com/flanksource/clicky-ui/issues",
@@ -12,6 +12,8 @@
   },
   "files": [
     "dist",
+    "oxlint-plugins/**/*.js",
+    "oxlint-plugins/README.md",
     "README.md",
     "LICENSE",
     "NOTICE.md"
@@ -40,6 +42,16 @@
       "import": "./dist/hooks.js",
       "require": "./dist/hooks.cjs"
     },
+    "./mdx-editor": {
+      "types": "./dist/mdx-editor.d.ts",
+      "import": "./dist/mdx-editor.js",
+      "require": "./dist/mdx-editor.cjs"
+    },
+    "./jotai": {
+      "types": "./dist/jotai.d.ts",
+      "import": "./dist/jotai.js",
+      "require": "./dist/jotai.cjs"
+    },
     "./components": {
       "types": "./dist/components.d.ts",
       "import": "./dist/components.js",
@@ -80,7 +92,9 @@
       "import": "./dist/ai.js",
       "require": "./dist/ai.cjs"
     },
+    "./oxlint-plugins": "./oxlint-plugins/clicky-ui.js",
     "./styles.css": "./dist/styles.css",
+    "./mdx-editor.css": "./dist/mdx-editor.css",
     "./tailwind-preset": {
       "types": "./dist/tailwind-preset.d.ts",
       "import": "./dist/tailwind-preset.js",
@@ -99,11 +113,13 @@
     "@tanstack/react-query": "^5.66.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "dompurify": "^3.4.7",
+    "dompurify": "^3.4.11",
+    "jotai": "^2.20.1",
     "tailwind-merge": "^2.6.0"
   },
   "devDependencies": {
     "@ai-sdk/react": "^3.0.201",
+    "@mdxeditor/editor": "^4.0.4",
     "@oxlint/plugins": "^1.60.0",
     "@storybook/react-vite": "10.3.5",
     "@tailwindcss/cli": "^4.2.4",
@@ -122,12 +138,13 @@
     "tailwindcss": "^4.2.4",
     "tsx": "^4.7.0",
     "typescript": "^5.7.2",
-    "vite": "^6.0.3",
+    "vite": "^6.4.3",
     "vite-plugin-dts": "^4.3.0",
-    "vitest": "^3.0.5"
+    "vitest": "^3.2.6"
   },
   "peerDependencies": {
     "@ai-sdk/react": "^3.0.0",
+    "@mdxeditor/editor": "^4.0.4",
     "@shikijs/langs": "^1.24.0",
     "@shikijs/themes": "^1.24.0",
     "@shikijs/transformers": "^1.24.0",
@@ -151,6 +168,9 @@
     "ai": {
       "optional": true
     },
+    "@mdxeditor/editor": {
+      "optional": true
+    },
     "@shikijs/langs": {
       "optional": true
     },