@siyahi/tools 0.1.9-next.32 → 0.1.9-next.34

package/README.md

@@ -49,6 +49,14 @@ flex-col gap-4">`, `<TableCell><span className="font-mono">`,
 A Vite+ or ESLint config can spread every rule at once:
 `import { recommended } from "@siyahi/tools/lint"`.
 
+One more rule is for a component library's own types rather than for pages, so
+it runs in every file it is turned on for and is not in `recommended`:
+`siyahi/optional-accepts-undefined` rejects an optional property that does not
+take undefined, such as `tone?: Tone`, and `--fix` writes
+`tone?: Tone | undefined`. Under TypeScript's `exactOptionalPropertyTypes` a
+page can only pass `tone: loss ? "negative" : undefined` to the second.
+Siyahi runs it on its own package.
+
 ## Font preload
 
 A Vite plugin that adds `<link rel="preload" as="font">` tags to the built
@@ -170,6 +178,7 @@ the surface under it. It fails unless text reaches 4.5:1 on the page, on its own
 fill and on the tints Siyahi's components put it on (Callout washes, the
 destructive tint and its hover, code-line fills, treemap heat steps), a field's
 edge, the focus ring, a selected tab and every chart and meaning colour reach
-3:1 against what is next to them, and every colour sits inside sRGB. Slots two
+3:1 against what is next to them, every bar colour's tint (`--bar-tint`) reaches
+1.5:1 against the card and each slot's against the next slot's, and every colour sits inside sRGB. Slots two
 apart share a lightness and are told apart by hue, so series take slots in
 order.

package/contrast.mjs

@@ -35,6 +35,12 @@ import { readTheme } from "./theme.mjs";
 
 const TEXT = 4.5;
 const MARK = 3;
+// A fill told apart from the fill or card beside it, inside a 1px edge that already carries the mark's 3:1. Only a
+// nearly solid tint reaches 3:1 against its neighbour's: the solid slots next to each other sit just over 3:1, and
+// mixing both into the card narrows that. At 25% a stack's pale segments sat at 1.2:1 against each other and read as
+// one, and a pale slot's lone bar at 1.3:1 against the card. 1.5:1 is a guard against sliding back there, not a
+// published threshold.
+const FILL = 1.5;
 const SURFACES = ["background", "card"];
 const CHARTS = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5"];
 
@@ -145,11 +151,21 @@ const PAIRS = [
   // The selected tab's fill against its list.
   { fg: "foreground", bg: "muted", min: MARK },
   // Chart marks on the canvas and the card. A bar is read by its full-colour
-  // edge, so these are the edges too; the tint inside is carried by the edge and
-  // has no pair of its own, nor has a dimmed bar's fainter tint. A stale
-  // block's marks (greyed, at 65%) are exempt: stale is meant to read faintly.
+  // edge, so these are the edges too. A stale block's marks (greyed, at 65%)
+  // are exempt: stale is meant to read faintly.
   ...[...CHARTS, "positive", "negative"].map((fg) => ({ fg, bg: "", min: MARK })),
   ...CHARTS.slice(0, -1).map((fg, i) => ({ fg, bg: CHARTS[i + 1] ?? "", min: MARK })),
+  // A bar's tint (--bar-tint) carries its colour where the bar is short, such as
+  // a thin stacked segment that is mostly edge: every bar colour's tint against
+  // the card, and each slot's against the next slot's, its neighbour in a stack.
+  // A dimmed bar's fainter tint has no pair: a selection means it to fade.
+  ...[...CHARTS, "positive", "negative"].map((fg) => ({ fg: `${fg}@bar-tint`, bg: "", min: FILL, surface: "card" })),
+  ...CHARTS.slice(0, -1).map((slot, i) => ({
+    fg: `${slot}@bar-tint`,
+    bg: `${CHARTS[i + 1]}@bar-tint`,
+    min: FILL,
+    surface: "card",
+  })),
   // Every bar colour against the 40% muted band a chart card lays behind a
   // hovered category (lib/chart-frame).
   ...[...CHARTS, "positive", "negative"].map((fg) => ({ fg, bg: "muted/40", min: MARK, surface: "card" })),

package/lint/index.mjs

@@ -2,7 +2,8 @@
 // Oxlint (and ESLint) plugin `siyahi`. Every rule runs only in files that
 // import `@siyahi/ui`, so pages written before Siyahi stay outside the rules
 // without any configuration. Three rules come from @shadcn/lint; the other
-// four cover what it does not check.
+// four cover what it does not check. One more, optional-accepts-undefined, is
+// for a component library's own types: unscoped, and not in `recommended`.
 import { plugin as shadcn } from "@shadcn/lint";
 
 /** @typedef {{ sourceCode: { text: string }, report: (problem: { node: unknown, message: string }) => void }} Context */
@@ -138,6 +139,88 @@ const noChartThemeMap = {
   }),
 };
 
+/** Types that already hold undefined, so they need no `| undefined`. */
+const HOLDS_UNDEFINED = new Set(["TSUndefinedKeyword", "TSAnyKeyword", "TSUnknownKeyword", "TSVoidKeyword"]);
+/** Types that bind looser than `|`, so a union with undefined wraps them in brackets. */
+const LOOSE = new Set(["TSFunctionType", "TSConstructorType", "TSConditionalType"]);
+
+/**
+ * @param {{ type: string, types?: { type: string }[], typeName?: { type: string, name?: string, right?: { name?: string } } }} type
+ * @returns {boolean}
+ */
+function holdsUndefined(type) {
+  if (HOLDS_UNDEFINED.has(type.type)) return true;
+  if (type.type === "TSUnionType") return (type.types ?? []).some(holdsUndefined);
+  // React's ReactNode includes undefined.
+  const name = type.typeName?.type === "TSQualifiedName" ? type.typeName.right?.name : type.typeName?.name;
+  return type.type === "TSTypeReference" && name === "ReactNode";
+}
+
+/**
+ * Whether a node sits in the pattern a conditional type matches against, `T extends { x?: infer U } ? U : never`,
+ * where adding undefined would change what matches and what `infer` takes.
+ * @param {any} node
+ * @returns {boolean}
+ */
+function inPattern(node) {
+  for (let child = node; child.parent; child = child.parent) {
+    if (child.parent.type === "TSConditionalType" && child.parent.extendsType === child) return true;
+  }
+  return false;
+}
+
+/** @type {Rule} */
+const optionalAcceptsUndefined = {
+  meta: {
+    type: "problem",
+    fixable: "code",
+    docs: { description: "Require `| undefined` on an optional property, for pages under exactOptionalPropertyTypes." },
+  },
+  // Under exactOptionalPropertyTypes, `tone?: Tone` rejects `tone: loss ? "negative" : undefined`, the way a page
+  // writes a prop it sets only sometimes; `tone?: Tone | undefined` takes it.
+  create: (context) => {
+    const message =
+      "An optional property must also accept undefined: add `| undefined`, for pages under exactOptionalPropertyTypes.";
+    /**
+     * @param {any} node a property signature, class field or mapped type
+     * @param {any} type its type
+     */
+    function check(node, type) {
+      if (!type || holdsUndefined(type) || inPattern(node)) return;
+      context.report({
+        node,
+        message,
+        fix: (/** @type {any} */ fixer) =>
+          LOOSE.has(type.type)
+            ? [fixer.insertTextBefore(type, "("), fixer.insertTextAfter(type, ") | undefined")]
+            : fixer.insertTextAfter(type, " | undefined"),
+      });
+    }
+    return {
+      /** @param {any} node */
+      TSPropertySignature(node) {
+        if (node.optional) check(node, node.typeAnnotation?.typeAnnotation);
+      },
+      /** @param {any} node */
+      PropertyDefinition(node) {
+        if (node.optional) check(node, node.typeAnnotation?.typeAnnotation);
+      },
+      /** @param {any} node `[K in keyof T]?: T[K]` */
+      TSMappedType(node) {
+        if (node.optional === true || node.optional === "+") check(node, node.typeAnnotation);
+      },
+      /** @param {any} node `onSelect?(): void`, which has no type to add undefined to */
+      TSMethodSignature(node) {
+        if (!node.optional || inPattern(node)) return;
+        context.report({
+          node,
+          message: `${message} Write it as a property: \`onSelect?: (() => void) | undefined\`.`,
+        });
+      },
+    };
+  },
+};
+
 /**
  * Options for shadcn's no-restyle, so every app gets the same policy from
  * `"siyahi/no-restyle": "error"` alone. Pages may place a component (margin,
@@ -163,24 +246,28 @@ function withOptions(rule, options) {
   };
 }
 
+/** Rules for pages that use Siyahi. */
+const pageRules = {
+  "no-color-literal": scoped(noColorLiteral),
+  "no-scheme-variant": scoped(noSchemeVariant),
+  "no-numeric-font-size": scoped(noNumericFontSize),
+  "no-chart-theme-map": scoped(noChartThemeMap),
+  "no-raw-colors": scoped(shadcn.rules["no-raw-colors"]),
+  "no-arbitrary-values": scoped(shadcn.rules["no-arbitrary-values"]),
+  "no-restyle": scoped(withOptions(shadcn.rules["no-restyle"], RESTYLE)),
+};
+
 /** @type {{ meta: { name: string }, rules: Record<string, Rule> }} */
 const plugin = {
   meta: { name: "siyahi" },
-  rules: {
-    "no-color-literal": scoped(noColorLiteral),
-    "no-scheme-variant": scoped(noSchemeVariant),
-    "no-numeric-font-size": scoped(noNumericFontSize),
-    "no-chart-theme-map": scoped(noChartThemeMap),
-    "no-raw-colors": scoped(shadcn.rules["no-raw-colors"]),
-    "no-arbitrary-values": scoped(shadcn.rules["no-arbitrary-values"]),
-    "no-restyle": scoped(withOptions(shadcn.rules["no-restyle"], RESTYLE)),
-  },
+  // optional-accepts-undefined is for a component library's own types, not for pages, which only use them.
+  rules: { ...pageRules, "optional-accepts-undefined": optionalAcceptsUndefined },
 };
 
 /**
- * Every rule at "error", for a Vite+ or ESLint config to spread.
+ * Every page rule at "error", for a Vite+ or ESLint config to spread.
  * @type {Record<string, "error">}
  */
-export const recommended = Object.fromEntries(Object.keys(plugin.rules).map((name) => [`siyahi/${name}`, "error"]));
+export const recommended = Object.fromEntries(Object.keys(pageRules).map((name) => [`siyahi/${name}`, "error"]));
 
 export default plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siyahi/tools",
-  "version": "0.1.9-next.32",
+  "version": "0.1.9-next.34",
   "description": "Checks and build helpers for Siyahi pages: a lint plugin, a font preload plugin, a theme contrast check, and screenshot and layout shift scripts.",
   "homepage": "https://siyahi.jatinbansal.com",
   "license": "MIT",

package/types/lint/index.d.mts

@@ -19,7 +19,7 @@ declare const plugin: {
     rules: Record<string, Rule>;
 };
 /**
- * Every rule at "error", for a Vite+ or ESLint config to spread.
+ * Every page rule at "error", for a Vite+ or ESLint config to spread.
  * @type {Record<string, "error">}
  */
 export declare const recommended: Record<string, "error">;