@flanksource/clicky-ui 0.3.6 → 0.3.8

package/oxlint-plugins/README.md

@@ -0,0 +1,148 @@
+# clicky-ui lint rules
+
+Custom [oxlint](https://oxc.rs/docs/guide/usage/linter/js-plugins.html) rules that
+projects **consuming** `@flanksource/clicky-ui` can enable to keep their code on
+the library's components, overlays, theming and icons instead of re-implementing
+them by hand.
+
+The rules ship as a JS plugin inside the published package
+(`@flanksource/clicky-ui/oxlint-plugins`), so a downstream repo can turn them on
+without copying anything.
+
+## Setup
+
+These rules require oxlint's [JS plugins](https://oxc.rs/docs/guide/usage/linter/js-plugins.html)
+(oxlint `>=1.50`, Node `>=20.19`). Add the plugin and the rules you want to your
+downstream `.oxlintrc.json`:
+
+```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"
+  }
+}
+```
+
+The `specifier` form resolves through the package's `exports` map. If your
+toolchain can't resolve it, point `jsPlugins` at the file directly instead:
+
+```json
+{
+  "jsPlugins": ["./node_modules/@flanksource/clicky-ui/oxlint-plugins/clicky-ui.js"]
+}
+```
+
+Every rule is **opt-in** — nothing is enabled until you list it. Choose the
+severity (`"warn"` / `"error"`) per rule.
+
+## Rules
+
+| Rule | Flags | Use instead |
+| --- | --- | --- |
+| `clicky-ui/prefer-clicky-components` | Native `<button>`, `<select>`, `<table>`, `<dialog>` that re-implement a shipped component | `Button`/`IconButton`, `Select`/`Combobox`, `DataTable`, `Modal` |
+| `clicky-ui/no-adhoc-overlay` | `role="dialog"`/`"alertdialog"`, arbitrary `z-[N]` classes, `style={{ zIndex: N }}` | `Modal`, `DropdownMenu`, `Toast`, and the `zIndex` scale |
+| `clicky-ui/prefer-tailwind-classes` | Inline `style` with **static** spacing/layout/typography values (`padding`, `margin`, `gap`, `display`, `fontWeight`, …) | Tailwind utilities + density utilities (`p-density-4`, `gap-density-2`) |
+| `clicky-ui/prefer-theme-tokens` | Hardcoded colors (`text-[#fff]`, `style={{ color: "#fff" }}`) and hand-reading the `clicky-ui-theme`/`clicky-ui-density` storage keys | Semantic tokens (`text-foreground`, `bg-background`, …) and the `useTheme`/`useDensity` hooks |
+| `clicky-ui/prefer-clicky-icons` | Icon imports from third-party libraries (lucide, react-icons, heroicons, MUI, phosphor, tabler, font-awesome, …), emoji used as icons, and raw iconify name strings (`codicon:clock`, `lucide:activity`, …) passed as a value/argument | `@flanksource/clicky-ui/icons` (`Ui*`), `@flanksource/icons/mi`, or `@iconify/react` |
+
+### `prefer-clicky-components`
+
+Rebuilding a primitive by hand means re-doing its styling, theming, density and
+accessibility — and drifting from the library over time. Reuse the component.
+
+```tsx
+// ✗ flagged
+<button onClick={save}>Save</button>;
+
+// ✓
+import { Button } from "@flanksource/clicky-ui/components";
+<Button onClick={save}>Save</Button>;
+```
+
+### `no-adhoc-overlay`
+
+Overlays must share clicky-ui's centralized z-index scale (`overlay/zIndex.ts`)
+so a dropdown opened inside a modal can't render behind it. Arbitrary `z-[N]`
+Tailwind classes are doubly bad: a consumer's Tailwind build only emits the
+arbitrary classes it can scan from the published dist, so a fresh `z-[N]` may
+compile to nothing.
+
+```tsx
+// ✗ flagged
+<div role="dialog" className="z-[9999]">…</div>;
+
+// ✓
+import { Modal } from "@flanksource/clicky-ui/components";
+<Modal open={open} onClose={close}>…</Modal>;
+```
+
+### `prefer-tailwind-classes`
+
+Static inline styles bypass Tailwind and the density system. **Computed** values
+(`var()`, `calc()`, `clamp()`, identifiers, expressions) are intentionally
+allowed — those legitimately can't be a static class.
+
+```tsx
+// ✗ flagged
+<div style={{ padding: 8, gap: 4 }} />;
+
+// ✓
+<div className="p-density-4 gap-density-2" />;
+
+// ✓ allowed — dynamic value can't be a static class
+<div style={{ fontSize: "clamp(1rem, 18cqmin, 2.5rem)" }} />;
+```
+
+### `prefer-theme-tokens`
+
+Hardcoded colors don't flip with `[data-theme]`, defeating light/dark theming.
+Reading the storage keys by hand re-implements the hooks.
+
+```tsx
+// ✗ flagged
+<span className="text-[#111]" style={{ backgroundColor: "#fff" }} />;
+localStorage.getItem("clicky-ui-theme");
+
+// ✓
+<span className="text-foreground bg-background" />;
+import { useTheme } from "@flanksource/clicky-ui/hooks";
+const { theme } = useTheme();
+```
+
+### `prefer-clicky-icons`
+
+Icons should come from an approved source and be real components, not emoji,
+glyphs pulled from an unrelated icon library, or raw iconify name strings
+(known icon-set prefixes: `ph`, `lucide`, `codicon`, `tabler`, `mdi`,
+`svg-spinners`, `jb-expui-*`) passed as a value or argument.
+
+```tsx
+// ✗ flagged
+import { Star } from "lucide-react";
+<span>🔍</span>;
+const icon = "codicon:clock"; // raw iconify name string
+<Icon icon="lucide:activity" />;
+
+// ✓
+import { UiStar } from "@flanksource/clicky-ui/icons";
+import { K8SSecret } from "@flanksource/icons/mi";
+import { Icon } from "@iconify/react";
+```
+
+## Developing the rules
+
+Each rule lives in its own `clicky-ui-*.js` file and exports a pure predicate
+(e.g. `isArbitraryZIndexClass`, `isUnapprovedIconImport`) that is unit-tested in
+`clicky-ui.test.ts`. `clicky-ui.js` is the plugin entry that registers them. Run
+the tests with:
+
+```bash
+pnpm --filter @flanksource/clicky-ui test clicky-ui
+```

package/oxlint-plugins/clicky-ui-no-adhoc-overlay.js

@@ -0,0 +1,88 @@
+// clicky-ui/no-adhoc-overlay — keep overlays going through clicky-ui's Modal and
+// its centralized z-index scale (overlay/zIndex.ts) instead of hand-rolled
+// dialogs and arbitrary stacking values that silently fight the modal stack.
+
+import {
+  attributeName,
+  classTokens,
+  collectStrings,
+  numericLiteral,
+  propertyKey,
+  styleObject,
+} from "./clicky-ui-shared.js";
+
+// `z-[999]`, `hover:z-[999]`, `md:z-[var(--x)]` — an arbitrary Tailwind z-index.
+// Named utilities (`z-50`) are fine; only escape-hatch arbitrary values are flagged.
+const ARBITRARY_Z_CLASS = /(?:^|:)z-\[[^\]]+\]$/;
+const DIALOG_ROLES = new Set(["dialog", "alertdialog"]);
+
+/** True for an arbitrary `z-[…]` Tailwind class token (variant prefixes allowed). */
+export function isArbitraryZIndexClass(token) {
+  return typeof token === "string" && ARBITRARY_Z_CLASS.test(token);
+}
+
+/** True for a `role` value that turns a plain element into an ad-hoc dialog. */
+export function isDialogRole(value) {
+  return typeof value === "string" && DIALOG_ROLES.has(value);
+}
+
+const Z_INDEX_MESSAGE =
+  "Hardcoded z-index. Use clicky-ui's overlay components (Modal, DropdownMenu, " +
+  "Toast) or the `zIndex` scale from @flanksource/clicky-ui so stacking stays " +
+  "consistent — arbitrary z-[N] classes can also be dropped by a consumer's " +
+  "Tailwind build.";
+
+function checkClassName(node, context) {
+  if (attributeName(node) !== "className" && attributeName(node) !== "class") return;
+  for (const token of classTokens(collectStrings(node.value))) {
+    if (isArbitraryZIndexClass(token)) {
+      context.report({ message: Z_INDEX_MESSAGE, node });
+      return;
+    }
+  }
+}
+
+function checkStyleZIndex(node, context) {
+  if (attributeName(node) !== "style") return;
+  const object = styleObject(node);
+  if (!object) return;
+  for (const prop of object.properties) {
+    if (propertyKey(prop) === "zIndex" && numericLiteral(prop.value) !== undefined) {
+      context.report({ message: Z_INDEX_MESSAGE, node: prop });
+    }
+  }
+}
+
+function checkDialogRole(node, context) {
+  if (attributeName(node) !== "role") return;
+  const value = node.value?.type === "Literal" ? node.value.value : undefined;
+  if (isDialogRole(value)) {
+    context.report({
+      message:
+        `role="${value}" builds an ad-hoc dialog. Use clicky-ui's Modal, which ` +
+        "owns focus trapping and the modal z-index stack.",
+      node,
+    });
+  }
+}
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Use clicky-ui overlays and the centralized z-index scale instead of ad-hoc dialogs",
+    },
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        checkClassName(node, context);
+        checkStyleZIndex(node, context);
+        checkDialogRole(node, context);
+      },
+    };
+  },
+};
+
+export default rule;

package/oxlint-plugins/clicky-ui-prefer-components.js

@@ -0,0 +1,46 @@
+// clicky-ui/prefer-clicky-components — flag native DOM elements that re-implement
+// a component clicky-ui already ships, so consumers reuse the library instead of
+// rebuilding (and re-styling, re-theming) primitives by hand.
+
+import { intrinsicElementName } from "./clicky-ui-shared.js";
+
+// Intrinsic element → the clicky-ui component(s) that should replace it.
+const REPLACEMENTS = {
+  button: "Button or IconButton (@flanksource/clicky-ui/components)",
+  select: "Select or Combobox (@flanksource/clicky-ui/components)",
+  table: "DataTable (@flanksource/clicky-ui/data)",
+  dialog: "Modal (@flanksource/clicky-ui/components)",
+};
+
+/** The clicky-ui replacement for an intrinsic element name, else undefined. */
+export function clickyReplacementFor(elementName) {
+  if (typeof elementName !== "string") return undefined;
+  return REPLACEMENTS[elementName];
+}
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Reuse clicky-ui components instead of rebuilding native DOM elements by hand",
+    },
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        const element = intrinsicElementName(node);
+        const replacement = clickyReplacementFor(element);
+        if (!replacement) return;
+        context.report({
+          message:
+            `Avoid rebuilding <${element}>. Reuse ${replacement} so styling, ` +
+            "theming, density and accessibility stay consistent with clicky-ui.",
+          node,
+        });
+      },
+    };
+  },
+};
+
+export default rule;

package/oxlint-plugins/clicky-ui-prefer-icons.js

@@ -0,0 +1,121 @@
+// clicky-ui/prefer-clicky-icons — icons must come from an approved source, and
+// must be real icon components rather than emoji/text "labels".
+//
+// Approved sources:
+//   - @flanksource/clicky-ui/icons  (generated Ui* components, e.g. UiFullscreen)
+//   - @flanksource/icons/mi         (Material/brand glyphs)
+//   - @iconify/react                (the <Icon> primitive / iconify icons)
+//
+// Anti-patterns this flags:
+//   1. Importing icons from any other icon library (lucide, react-icons,
+//      heroicons, @mui/icons-material, phosphor, tabler, font-awesome, …).
+//   2. Using an emoji as an icon — a bare emoji JSX child, or an emoji passed to
+//      an `icon` prop — instead of a real icon component.
+//   3. Passing a raw iconify name string (e.g. "codicon:clock", "lucide:activity")
+//      as a value/argument instead of importing the generated Ui* component.
+
+import { attributeName, isIconifyName, literalString } from "./clicky-ui-shared.js";
+
+// Sources that are always fine (never flagged), even if a denylist pattern overlaps.
+const APPROVED_SOURCES = [
+  /^@iconify\/react(\/|$)/,
+  /^@iconify-icons\//,
+  /^@flanksource\/clicky-ui\/icons(\/|$)/,
+  /^@flanksource\/icons(\/|$)/,
+];
+
+// Third-party icon libraries consumers should not pull icons from directly.
+const ICON_LIBRARIES = [
+  /^lucide-react$/,
+  /^lucide$/,
+  /^react-icons(\/|$)/,
+  /^@heroicons\/react(\/|$)/,
+  /^@mui\/icons-material(\/|$)/,
+  /^@phosphor-icons\/react(\/|$)/,
+  /^@radix-ui\/react-icons$/,
+  /^@tabler\/icons-react$/,
+  /^react-feather$/,
+  /^feather-icons$/,
+  /^@fortawesome\//,
+  /^@ant-design\/icons(\/|$)/,
+  /^react-bootstrap-icons$/,
+  /^@primer\/octicons-react$/,
+  /^grommet-icons$/,
+];
+
+// A single emoji glyph: a pictographic code point plus its modifiers - ZWJ
+// (\u200d), variation selector (\uFE0F), combining enclosing keycap (\u20E3).
+// Expressed as alternation (not a character class) to avoid combining marks
+// inside `[...]` (oxlint no-misleading-character-class).
+const HAS_EMOJI = /\p{Extended_Pictographic}/u;
+const ALLOWED_GLYPH = /\s|\u200d|\uFE0F|\u20E3|\p{Extended_Pictographic}/gu;
+
+/** True when an import source is a disallowed third-party icon library. */
+export function isUnapprovedIconImport(source) {
+  if (typeof source !== "string") return false;
+  if (APPROVED_SOURCES.some((re) => re.test(source))) return false;
+  return ICON_LIBRARIES.some((re) => re.test(source));
+}
+
+/** True when a string is only emoji (used as a stand-in for a real icon). */
+export function isEmojiOnly(text) {
+  if (typeof text !== "string") return false;
+  const trimmed = text.trim();
+  if (!trimmed) return false;
+  if (!HAS_EMOJI.test(trimmed)) return false;
+  // Emoji-only ⇔ nothing remains after removing every emoji glyph + modifier.
+  return trimmed.replace(ALLOWED_GLYPH, "") === "";
+}
+
+const APPROVED_HINT =
+  "Import icons from @flanksource/clicky-ui/icons (Ui* components), " +
+  "@flanksource/icons/mi, or @iconify/react";
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Import icons from approved sources and use real icon components, not emoji/text labels",
+    },
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (isUnapprovedIconImport(node.source?.value)) {
+          context.report({
+            message: `"${node.source.value}" is not an approved icon source. ${APPROVED_HINT}.`,
+            node,
+          });
+        }
+      },
+      Literal(node) {
+        if (isIconifyName(node.value)) {
+          context.report({
+            message: `Iconify icon name "${node.value}" passed as a string. ${APPROVED_HINT} and pass the component.`,
+            node,
+          });
+        }
+      },
+      JSXText(node) {
+        if (isEmojiOnly(node.value)) {
+          context.report({
+            message: `Emoji used as an icon. ${APPROVED_HINT}.`,
+            node,
+          });
+        }
+      },
+      JSXAttribute(node) {
+        if (attributeName(node) !== "icon") return;
+        if (isEmojiOnly(literalString(node.value))) {
+          context.report({
+            message: `Emoji passed to \`icon\`. ${APPROVED_HINT} and pass the component.`,
+            node,
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/oxlint-plugins/clicky-ui-prefer-tailwind.js

@@ -0,0 +1,98 @@
+// clicky-ui/prefer-tailwind-classes — flag inline `style={{…}}` that hardcodes
+// spacing/layout/typography with static values which have direct Tailwind
+// utilities. Computed values (var()/calc()/clamp(), identifiers, expressions)
+// are intentionally allowed — those legitimately cannot be a static class.
+//
+// Color properties are deliberately NOT handled here; they belong to the theme
+// concern (clicky-ui/prefer-theme-tokens).
+
+import { attributeName, propertyKey, styleObject } from "./clicky-ui-shared.js";
+
+// CSS properties with a clean Tailwind utility equivalent (non-color).
+const TAILWIND_MAPPABLE = new Set([
+  "padding",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "paddingInline",
+  "paddingBlock",
+  "margin",
+  "marginTop",
+  "marginRight",
+  "marginBottom",
+  "marginLeft",
+  "marginInline",
+  "marginBlock",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "display",
+  "flexDirection",
+  "justifyContent",
+  "alignItems",
+  "textAlign",
+  "fontWeight",
+  "fontSize",
+  "lineHeight",
+  "borderRadius",
+]);
+
+// Dynamic CSS functions whose result can't be a static utility class.
+const DYNAMIC_CSS = /\b(?:var|calc|clamp|min|max|env)\(/;
+
+/**
+ * True when a style property should instead be a Tailwind class: it is a
+ * mappable property AND its value is a static literal (number, or string with
+ * no dynamic CSS function). `value` is the already-extracted literal value.
+ */
+export function isHandrolledStyleValue(property, value) {
+  if (!TAILWIND_MAPPABLE.has(property)) return false;
+  if (typeof value === "number") return true;
+  if (typeof value !== "string") return false;
+  return !DYNAMIC_CSS.test(value);
+}
+
+/** Extract a static literal value (string/number) from a Property value node. */
+function staticValue(node) {
+  if (node?.type === "Literal" && (typeof node.value === "string" || typeof node.value === "number")) {
+    return node.value;
+  }
+  return undefined;
+}
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Use Tailwind utility classes instead of hand-rolling static inline styles",
+    },
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        if (attributeName(node) !== "style") return;
+        const object = styleObject(node);
+        if (!object) return;
+        for (const prop of object.properties) {
+          const key = propertyKey(prop);
+          if (!key) continue;
+          const value = staticValue(prop.value);
+          if (value === undefined) continue;
+          if (isHandrolledStyleValue(key, value)) {
+            context.report({
+              message:
+                `Hand-rolled inline style \`${key}\`. Use the equivalent Tailwind ` +
+                "class (and density utilities like `p-density-4`/`gap-density-2`) " +
+                "so spacing tracks the active density.",
+              node: prop,
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/oxlint-plugins/clicky-ui-prefer-theme.js

@@ -0,0 +1,134 @@
+// clicky-ui/prefer-theme-tokens — keep consumers on the theme + density system
+// instead of bypassing it. Two anti-patterns:
+//   1. Hardcoded colors (className `text-[#fff]`, `style={{ color: "#fff" }}`)
+//      that don't flip with `[data-theme]` — use semantic tokens (text-foreground,
+//      bg-background, border-border, …).
+//   2. Re-reading the clicky theme/density localStorage keys by hand instead of
+//      the `useTheme`/`useDensity` hooks (or ThemeProvider/DensityProvider).
+
+import {
+  attributeName,
+  classTokens,
+  collectStrings,
+  literalString,
+  propertyKey,
+  styleObject,
+} from "./clicky-ui-shared.js";
+
+// Arbitrary Tailwind color class with a literal color, e.g. `text-[#fff]`,
+// `bg-[rgb(0,0,0)]`, `hover:border-[#abc]`.
+const ARBITRARY_COLOR_CLASS =
+  /(?:^|:)(?:text|bg|border|ring|fill|stroke|from|via|to|outline|caret|decoration|accent|shadow|divide)-\[(?:#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\()/;
+
+// A literal CSS color value: hex, rgb()/rgba(), hsl()/hsla().
+const HARDCODED_COLOR = /(?:#[0-9a-fA-F]{3,8}\b|\b(?:rgb|rgba|hsl|hsla)\()/;
+
+// CSS properties whose hardcoded color should be a theme token instead.
+const COLOR_PROPS = new Set([
+  "color",
+  "backgroundColor",
+  "background",
+  "borderColor",
+  "outlineColor",
+  "caretColor",
+  "textDecorationColor",
+  "fill",
+  "stroke",
+]);
+
+const STORAGE_KEYS = new Set(["clicky-ui-theme", "clicky-ui-density"]);
+const STORAGE_OBJECTS = new Set(["localStorage", "sessionStorage"]);
+
+/** True for a Tailwind class hardcoding a literal color (`text-[#fff]`). */
+export function isArbitraryColorClass(token) {
+  return typeof token === "string" && ARBITRARY_COLOR_CLASS.test(token);
+}
+
+/** True for a literal CSS color value (hex / rgb / hsl). */
+export function isHardcodedColorValue(value) {
+  return typeof value === "string" && HARDCODED_COLOR.test(value);
+}
+
+/** True for a clicky-ui theme/density localStorage key. */
+export function isClickyStorageKey(value) {
+  return typeof value === "string" && STORAGE_KEYS.has(value);
+}
+
+const TOKEN_HINT =
+  "use a semantic theme token (text-foreground, bg-background, border-border, …) " +
+  "so it tracks light/dark via [data-theme]";
+
+function checkClassName(node, context) {
+  if (attributeName(node) !== "className" && attributeName(node) !== "class") return;
+  for (const token of classTokens(collectStrings(node.value))) {
+    if (isArbitraryColorClass(token)) {
+      context.report({ message: `Hardcoded color \`${token}\` — ${TOKEN_HINT}.`, node });
+      return;
+    }
+  }
+}
+
+function checkStyleColor(node, context) {
+  if (attributeName(node) !== "style") return;
+  const object = styleObject(node);
+  if (!object) return;
+  for (const prop of object.properties) {
+    const key = propertyKey(prop);
+    if (!key || !COLOR_PROPS.has(key)) continue;
+    if (isHardcodedColorValue(literalString(prop.value))) {
+      context.report({
+        message: `Hardcoded \`${key}\` color — ${TOKEN_HINT}.`,
+        node: prop,
+      });
+    }
+  }
+}
+
+/** `localStorage`, `window.localStorage`, `globalThis.sessionStorage`, … */
+function isStorageObject(node) {
+  if (node?.type === "Identifier") return STORAGE_OBJECTS.has(node.name);
+  if (node?.type === "MemberExpression" && node.property?.type === "Identifier") {
+    return STORAGE_OBJECTS.has(node.property.name);
+  }
+  return false;
+}
+
+function checkStorageCall(node, context) {
+  const callee = node.callee;
+  if (callee?.type !== "MemberExpression") return;
+  if (!isStorageObject(callee.object)) return;
+  for (const arg of node.arguments) {
+    if (isClickyStorageKey(literalString(arg))) {
+      context.report({
+        message:
+          `Reading "${arg.value}" from storage by hand. Use clicky-ui's useTheme()/` +
+          "useDensity() hooks (or ThemeProvider/DensityProvider) instead.",
+        node,
+      });
+      return;
+    }
+  }
+}
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Use clicky-ui theme tokens and theme/density hooks instead of hardcoded colors or raw storage access",
+    },
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        checkClassName(node, context);
+        checkStyleColor(node, context);
+      },
+      CallExpression(node) {
+        checkStorageCall(node, context);
+      },
+    };
+  },
+};
+
+export default rule;