@yahoo/uds-create-config 5.61.1 → 5.62.0

package/dist/lint/rules.js

@@ -0,0 +1,466 @@
+import { isRef } from "../framework/utils/refs.js";
+import { resolveTokenValueUnder, stylePropEntries } from "../framework/projections.js";
+import { contrastRatio } from "../framework/utils/color.js";
+import { parseCssLength } from "../framework/utils/css-length.js";
+import "../index.js";
+import { MIN_CONTRAST, SCALE_STEP, TRANSPARENT, written } from "./context.js";
+//#region src/lint/rules.ts
+/**
+* Every lint rule: its group, what it detects, how to fix it, how loud it is by default, and what it
+* reads.
+*
+* - A rule that reads the config carries its `check` here, so it runs wherever a config is loaded:
+*   Create's browser on every edit, and `uds lint`.
+* - A rule that reads the sources is checked by a {@link LintSources} adapter, which `lint()` hands it
+*   to: codegen's reads the files on disk for `uds lint`, and Create's server reads a branch's sealed
+*   sources. Without one, as in Create's browser, those rules don't run.
+*/
+const AUTHORING_LINT_GROUPS = {
+	portability: {
+		title: "Portability",
+		about: "Values that reach a component only through code, so a team that links or extends your system can’t change them."
+	},
+	editability: {
+		title: "Editability",
+		about: "Behavior and styling decided in code, where Create can't show or change it. Turn this group off if your system is only ever edited in code."
+	},
+	maintainability: {
+		title: "Maintainability",
+		about: "Styles written longer than they need to be: values your tokens already hold, the same value repeated under every option, and settings that change nothing. Each makes the next change harder."
+	},
+	design: {
+		title: "Design",
+		about: "Contrast, spacing and sizing your users will notice: text that is hard to read, values just off your scale, colors that stay the same in dark mode, and targets too small to tap."
+	},
+	compatibility: {
+		title: "Compatibility",
+		about: "Reliance on parts of the platform that are changing or internal, which a future update can break."
+	},
+	nursery: {
+		title: "Nursery",
+		about: "New rules still being tuned. They are off unless you turn them on, and their advice may change.",
+		/** Naming the group turns none of them on: a nursery rule is taken up one at a time. */
+		defaultSeverity: "off"
+	}
+};
+const AUTHORING_LINT_RULES = {
+	"inline-style-on-layer": {
+		group: "portability",
+		label: "Inline style",
+		detects: "A style written directly on an element. It beats every rule, so no edit or override can change it.",
+		fix: "move the values into the layer's style rule; a value the render works out becomes a `.states()` entry a rule keys on"
+	},
+	"token-variable-as-text": {
+		group: "portability",
+		label: "Token spelled as text",
+		detects: "A token's CSS variable typed out by hand. Rename the token and this spot keeps the old name.",
+		fix: "reference the token: `Token.ref(path)` as a value, `[Token.ref(path).cssVariable.name()]` as a key; a value built from several tokens composes them with `shadow()`, `alpha()`, `timing()` or `transition()`"
+	},
+	"variable-channel": {
+		group: "portability",
+		label: "Private CSS variable",
+		detects: "A CSS variable the system sets and reads for itself, which overrides and linked systems can’t see.",
+		fix: "carry the value the way the reader can take it, which each site names: an element that reads it becomes a layer with the style property set on it, a motion preset takes a variant chosen by a state, a rule takes the value itself, and a runtime value is a prop forwarded to a style property"
+	},
+	"foreign-variable": {
+		group: "portability",
+		label: "Another package's variable",
+		detects: "A CSS variable from outside the system. Nothing records that the system depends on it.",
+		fix: "one the system sets for another library: declare it as a token under that exact name (`cssVariable: '--name'`) and reach it through `Token.ref`, so the dependency is on the record. One it only reads is blocked: a token would set it too, and could override the library's value"
+	},
+	"runtime-style-read": {
+		group: "editability",
+		label: "Style read while running",
+		detects: "A value measured in the browser at runtime, which the system's settings never see.",
+		fix: "a rule, a modifier (`_reducedMotion`, `_rtl`), logical properties, or a `Token.ref` reader"
+	},
+	"render-data-attribute": {
+		group: "editability",
+		label: "Hidden state",
+		detects: "A state the code sets for styling that the component doesn't declare, so Create can't show, force or preview it.",
+		fix: "a value the render knows becomes a `.states()` entry; a value from a declared prop becomes a `when: { prop }` rule"
+	},
+	"internal-marker": {
+		group: "compatibility",
+		fixKind: "blocked",
+		label: "Internal marker",
+		detects: "A platform-internal attribute written by hand, which an update can change without notice.",
+		fix: "use the public API that sets it; where none exists, report the gap rather than writing the marker"
+	},
+	"reserved-variable-name": {
+		group: "portability",
+		label: "Variable name a token could take",
+		detects: "A hand-written CSS variable named like a token, which a future token could collide with.",
+		fix: "rename it outside the generated prefixes, or make it a token so the build owns the name"
+	},
+	"override-copies-source": {
+		group: "portability",
+		fixKind: "auto",
+		label: "Copied instead of extended",
+		detects: "An override that copies a linked system's whole list to add to it, so later additions upstream never arrive.",
+		fix: "`extend` the list with only the additions, or drop the override when it adds nothing. Order matters only where two entries share a name, since the earlier one wins"
+	},
+	"number-in-brackets": {
+		reads: "both",
+		group: "maintainability",
+		label: "Number written as text",
+		detects: "A number wrapped in brackets, like [240px], where the plain number works and reads better.",
+		fix: "write the number (`width: 240`); a property most of whose bracketed values are px takes `arbitrary: 'px'` first, and one whose are plain numbers `arbitrary: 'unitless'`",
+		fixKind: "auto",
+		check: { value: numberInBrackets }
+	},
+	"unused-token-group": {
+		group: "nursery",
+		label: "Unused token group",
+		detects: "A group of tokens a property offers that nothing picks.",
+		fix: "drop the group from the property's `values`, once the systems and apps in other repos that use it are checked too"
+	},
+	"duplicate-value-name": {
+		group: "portability",
+		label: "Two values, one name",
+		detects: "A property that offers two values under the same name. Only one can ever be picked.",
+		fix: "rename one of them, or drop the one that isn’t wanted, so each name means one value"
+	},
+	"render-default": {
+		group: "editability",
+		label: "Default hidden in code",
+		detects: "A default value chosen in code rather than in the component's settings, so Create shows a different default than what renders.",
+		fix: "move it into `.defaultProps({ … })`; a default the component already declares is deleted from the render"
+	},
+	"undeclared-prop": {
+		group: "editability",
+		label: "Property Create can't see",
+		detects: "A property the component uses that it doesn't declare, so it doesn't show in the panel and can't be set or previewed.",
+		fix: "declare it in `.props()` with the type it takes; a handler is a forward to the layer that takes it"
+	},
+	"state-for-modifier": {
+		group: "editability",
+		label: "Hover tracked in code",
+		detects: "Hover or focus tracked by code, where a built-in state would do the same and show in Create.",
+		fix: "write the rules it chooses under the modifier the handlers follow (`_hover`, `_focus`, `_focusVisible`, `_focusWithin`, or a `_group…` one for a parent), and drop the state and its handlers"
+	},
+	"forward-replaced-by-render": {
+		group: "editability",
+		label: "Content overridden in code",
+		detects: "Content the component says goes to a layer, which the code replaces, so what you set doesn't show.",
+		fix: "say what the render does: a prop the render places itself is a slot (or a `string`), and the forward goes; content the layer should take as it is is the forward, and the render's children go"
+	},
+	"glyph-in-render": {
+		group: "editability",
+		label: "Icon chosen in code",
+		detects: "An icon the code picks, which Create can't show or swap.",
+		fix: "set `name` in a rule on the icon layer, one per value of the prop or state that picks it"
+	},
+	"computed-config": {
+		group: "editability",
+		label: "Styles built by code",
+		detects: "Styles or options assembled by code (a shared constant, a spread or a condition). Create can show them but an edit can’t be written back.",
+		fix: "write the value in place, as a literal or a `Token.ref`; a list shared with code is written in the config and read from it"
+	},
+	"restated-in-every-variant": {
+		group: "maintainability",
+		label: "Same value in every option",
+		detects: "A value set identically under every option of a property. It never varies, so it belongs in the component's base style.",
+		fix: "set it once, in the base rule"
+	},
+	"variant-passthrough": {
+		group: "nursery",
+		label: "One rule per option",
+		detects: "A separate rule for each option that only passes the option along, so every new option needs a new rule.",
+		fix: "forward the prop to the layer: `{ type: 'forward', target: '<layer>/<prop>' }`"
+	},
+	"no-op-modifier": {
+		group: "maintainability",
+		label: "State that changes nothing",
+		detects: "A hover, focus or mode style that sets a value to what it already is.",
+		fix: "delete it, once no system that links this one relies on it: one that changes the value but not the modifier's keeps the modifier's here, and loses it when it's deleted. The finding carries the deletion for whoever makes it"
+	},
+	"inherited-value-restated": {
+		group: "maintainability",
+		label: "Repeats its parent",
+		detects: "A layer set to the same value it already gets from the layer around it.",
+		fix: "delete the layer's entry, so it inherits as the base rule says, once no system that links this one relies on it: one that changes the parent's value keeps the layer's here, and the layer follows the parent once it's deleted. The finding carries the deletion for whoever makes it"
+	},
+	"hand-forwarded-prop": {
+		group: "editability",
+		label: "Property passed along in code",
+		detects: "A property the code hands to one layer by hand. Declaring where it goes lets Create show it and lets linked systems route it.",
+		fix: "declare it as a forward to that layer, `{ type: 'forward', target: '<layer>/<attribute>' }`, and drop it from the render; an element that isn't a layer becomes one first"
+	},
+	"literal-matches-token": {
+		reads: "both",
+		group: "maintainability",
+		label: "Value a token holds",
+		detects: "A value typed by hand that one of your tokens already holds. Change the token and this spot is left behind.",
+		fix: "use the token's name, as the style property takes it (`padding: '2'`)",
+		check: { value: literalMatchesToken }
+	},
+	"layer-bundle-split": {
+		group: "editability",
+		label: "Layer split apart in code",
+		detects: "A layer's styling taken apart in code and partly applied elsewhere, so Create's edits land in the wrong place.",
+		fix: "spread each layer's bundle whole on its element, and declare each prop another element takes as a forward to its layer, by name (`{ type: 'forward', target: 'input/onChange' }`); a value read off a bundle to compute with goes in a rule"
+	},
+	"context-carried-variant": {
+		group: "editability",
+		label: "Option passed down invisibly",
+		detects: "A size or variant a part inherits from its parent behind the scenes, which Create doesn't know about.",
+		fix: "a rule on the parent that sets the part's layer: `{ when: { size: 'sm' }, layers: { item: { size: 'sm' } } }`; parts rendered in a list wait on repeated parts"
+	},
+	"forced-prop-in-render": {
+		group: "editability",
+		label: "Value fixed in code",
+		detects: "A style or option the code sets on a nested component, which Create can't change.",
+		fix: "set it in a rule on that layer (`layers: { action: { variant: 'ghost' } }`), one per case for a picked value, making the element a layer first if it isn't one"
+	},
+	"ref-replaced-by-literal": {
+		group: "portability",
+		label: "Linked token copied",
+		detects: "A linked token replaced by the value it already had, so it stops following the system it came from.",
+		fix: "drop the override, or keep the ref the source has"
+	},
+	"shadowed-pin-directive": {
+		group: "portability",
+		label: "Option that does nothing",
+		detects: "A linked system's setting for a component this system replaces with its own, so the setting has no effect.",
+		fix: "delete the option, or move what it sets onto this system's own component"
+	},
+	"implicit-children": {
+		group: "compatibility",
+		label: "Content not declared",
+		detects: "Content the component accepts without declaring it. The old way is going away, and Create can't see it until then.",
+		fix: "declare it: `children: { type: 'slot' }`, or a forward to the layer the render places it in, `{ type: 'forward', target: '<layer>/children' }`"
+	},
+	"copied-component": {
+		group: "nursery",
+		label: "Copied component",
+		detects: "A component whose styles are another's, word for word, so a change to one doesn't reach the other.",
+		fix: "extend the other, `Component.ref('Other').extend({ … })`, and keep only what differs; two near copies extend one component both share"
+	},
+	"low-contrast": {
+		group: "design",
+		reads: "config",
+		label: "Low contrast",
+		detects: "Text that is hard to read against its background in light or dark mode. Text needs 4.5:1, icons 3:1.",
+		fix: "pick a text or background token that clears 4.5:1 in every mode",
+		check: { layer: lowContrast }
+	},
+	"near-token": {
+		group: "design",
+		reads: "config",
+		label: "Almost a token",
+		detects: "A value a pixel or so off one of your tokens. Usually a typo; if it's on purpose, it may belong on the scale.",
+		fix: "use the token when it was meant; if the value is on purpose, it may belong on the scale",
+		check: { value: nearToken }
+	},
+	"fixed-in-dark-mode": {
+		group: "design",
+		reads: "config",
+		label: "Same in dark mode",
+		detects: "A color that doesn't change in dark mode while the rest of the component does.",
+		fix: "use a token that has a dark value, or give this one a `_dark` value",
+		check: { component: fixedInDarkMode }
+	},
+	"small-tap-target": {
+		group: "design",
+		reads: "config",
+		label: "Small tap target",
+		detects: "Something you press that is too small to hit reliably: under 24 × 24 px on the web, 44 × 44 pt in a native app.",
+		fix: "make it at least that size each way, or grow its hit area with padding",
+		check: { layer: smallTapTarget }
+	},
+	"duplicate-token": {
+		group: "design",
+		reads: "config",
+		label: "Two tokens, one value",
+		detects: "Two steps on a scale that hold the same value, so nobody can tell which to pick.",
+		fix: "keep one, or make the other a reference to it (`Token.ref(…)`) so the two are one decision",
+		check: { system: duplicateToken }
+	},
+	"wildcard-forward": {
+		group: "nursery",
+		label: "Accepts anything",
+		detects: "A component that passes along every property it gets. It will soon accept only what it declares.",
+		fix: "declare each one as `{ type: 'forward', target: '<layer>/<prop>' }` and drop the entry. A list is ready; a `'*'` waits on what callers outside the files read pass, and on the prop type it names (`type: 'modifier'`, the `as` element forward)"
+	}
+};
+/** What a rule checks; see `reads` on {@link AUTHORING_LINT_RULES}. */
+const lintReads = (rule) => {
+	const entry = AUTHORING_LINT_RULES[rule];
+	return "reads" in entry ? entry.reads : "code";
+};
+/** The rules that read the config, which `lintConfig` runs wherever a config is loaded. */
+const CONFIG_LINT_RULES = Object.keys(AUTHORING_LINT_RULES).filter((rule) => lintReads(rule) !== "code");
+/** A rule's severity as `settings.lint.rules` sets it: its own entry, else its group's, else the
+*  group's default. */
+function ruleSeverity(rule, severities) {
+	const { group } = AUTHORING_LINT_RULES[rule];
+	const groupAbout = AUTHORING_LINT_GROUPS[group];
+	const fallback = "defaultSeverity" in groupAbout ? groupAbout.defaultSeverity : "warn";
+	return severities[rule] ?? (fallback === "off" ? "off" : severities[group]) ?? fallback;
+}
+/** literal-matches-token: the same text a token holds. */
+function literalMatchesToken(ctx, value, report) {
+	const match = ctx.tokenSpelled(value.site);
+	if (!match) return;
+	report({
+		at: value,
+		message: `\`${value.bracketed}\` is what ${value.site.prop}'s \`${match.name}\` holds. Use the token, so a change to it reaches this layer.`,
+		suggestion: match.name
+	});
+}
+/** Whether `literal-matches-token` already reports a value, which the other value checks then leave. */
+const spelledOut = (ctx, value) => ctx.runs("literal-matches-token") && ctx.tokenSpelled(value.site) !== void 0;
+/** number-in-brackets: a property that reads bare numbers, written in brackets. */
+function numberInBrackets(ctx, value, report) {
+	const { bracketed, site } = value;
+	if (!bracketed || spelledOut(ctx, value)) return;
+	const reads = ctx.values.arbitrary.get(site.prop);
+	if (reads !== "px" && reads !== "unitless") return;
+	const length = parseCssLength(bracketed);
+	if (!length || length.unit === "rem") return;
+	if ((length.unit === "px" ? "px" : "unitless") !== reads) return;
+	const bare = bracketed.trim().replace(/px$/, "");
+	report({
+		at: value,
+		message: `\`${site.prop}\` takes a number in ${reads === "px" ? "px" : "as it is"}: write \`${bare}\`.`,
+		suggestion: bare
+	});
+}
+/** near-token: off a token by a pixel or so. */
+function nearToken(ctx, value, report) {
+	const { site } = value;
+	if (!value.bracketed && typeof site.value !== "number") return;
+	if (spelledOut(ctx, value)) return;
+	const px = value.px();
+	const tokens = ctx.tokensFor(site.prop).filter((one) => one.px !== void 0);
+	if (px === void 0 || px === 0 || tokens.length < 3) return;
+	const nearest = tokens.map((one) => ({
+		...one,
+		off: Math.abs(one.px - px)
+	})).sort((a, b) => a.off - b.off)[0];
+	if (!nearest || nearest.off <= 0 || nearest.off > Math.max(1, nearest.px * .05) || tokens.some((one) => one.px === px)) return;
+	report({
+		at: value,
+		message: `\`${written(site.value)}\` is ${Math.round(nearest.off * 100) / 100}px off ${site.prop}'s \`${nearest.name}\` (${nearest.literal}${/rem$/.test(nearest.literal) ? `, ${nearest.px}px at a 16px root` : ""}).`,
+		suggestion: nearest.name
+	});
+}
+/** fixed-in-dark-mode: colors that hold still while the component's others change. */
+function fixedInDarkMode(ctx, component, report) {
+	const { values, modes } = ctx;
+	if (modes.length <= 1) return;
+	const { sites } = component;
+	const leaf = (modifier) => modifier.replace(/^_/, "");
+	const modeOptions = new Set(modes.map(({ label }) => label));
+	const otherModes = new Set(modes.filter(({ condition }) => condition !== null).map(({ label }) => label));
+	const colors = sites.filter((site) => values.colorKeys.has(site.prop) && !site.modifiers.some((one) => modeOptions.has(leaf(one)))).map((site) => ctx.value(component, site));
+	const changes = (value) => modes.some((mode) => mode.condition !== null && String(value.literal(mode)).toLowerCase() !== String(value.literal()).toLowerCase());
+	const changing = colors.filter(changes);
+	if (changing.length < 2) return;
+	const darkSet = new Set(sites.filter((site) => site.modifiers.some((one) => otherModes.has(leaf(one)))).map((site) => `${site.when}|${site.layer}|${site.prop}`));
+	const dark = modes.find(({ condition }) => condition !== null)?.label ?? "dark";
+	for (const value of colors) {
+		const { site } = value;
+		if (changing.includes(value)) continue;
+		if (darkSet.has(`${site.when}|${site.layer}|${site.prop}`)) continue;
+		const literal = value.literal();
+		if (typeof literal !== "string" || TRANSPARENT.test(literal.trim())) continue;
+		const color = value.color();
+		if (!color || color[3] === 0) continue;
+		report({
+			at: value,
+			message: value.token ? `\`${value.token}\` is ${literal} in ${dark} mode too, while ${changing.length} of this component's colors change.` : `\`${written(site.value)}\` is written as a color, so it stays ${literal} in ${dark} mode while ${changing.length} of this component's colors change.`
+		});
+	}
+}
+/** low-contrast: a layer's text over its background, in each mode. */
+function lowContrast(ctx, layer, report) {
+	if (!layer.ownText && !layer.ownBackground) return;
+	const { text, background } = layer;
+	if (!text || !background) return;
+	if (written(text.site.value) === written(background.site.value)) return;
+	const minimum = layer.graphic ? 3 : MIN_CONTRAST;
+	for (const mode of ctx.modes) {
+		const fg = text.color(mode);
+		const bg = background.color(mode);
+		if (!fg || !bg || bg[3] < 1 || fg[3] === 0) continue;
+		const ratio = contrastRatio(fg, bg);
+		if (ratio >= minimum) continue;
+		const contrast = {
+			component: layer.component,
+			text: text.site,
+			background: background.site,
+			minimum
+		};
+		const backdrop = ctx.passingToken({
+			change: "background",
+			...contrast
+		});
+		const recolor = backdrop ? void 0 : ctx.passingToken({
+			change: "text",
+			...contrast
+		});
+		let advice = "";
+		if (backdrop) advice = ` \`${backdrop.token}\` is the closest background that clears it in every mode.`;
+		else if (recolor) advice = ` \`${recolor.token}\` is the closest text color that clears it in every mode.`;
+		report({
+			at: text,
+			message: `\`${written(text.site.value)}\` on \`${written(background.site.value)}\` is ${(Math.floor(ratio * 100) / 100).toFixed(2)}:1 in ${mode.label} mode${layer.where ? ` (${layer.where})` : ""}; ${minimum === 4.5 ? "text" : "an icon"} needs ${minimum}:1.${advice}`,
+			...backdrop ? {
+				suggestion: backdrop.name,
+				fixAt: background
+			} : {},
+			...recolor ? { suggestion: recolor.name } : {}
+		});
+		return;
+	}
+}
+/** small-tap-target: the root of something you press, under the platform's minimum. */
+function smallTapTarget(ctx, layer, report) {
+	if (!layer.pressable) return;
+	const { minTarget, unit } = ctx.platform;
+	for (const [value, reads] of [[layer.height, "tall"], [layer.width, "wide"]]) {
+		const px = value?.px();
+		if (!value || px === void 0 || px <= 0 || px >= minTarget) continue;
+		report({
+			at: value,
+			message: `${layer.where ? `At ${layer.where}, it` : "It"}'s ${px}${unit} ${reads}; a target you press needs ${minTarget}${unit}.`
+		});
+	}
+}
+/** duplicate-token: two tokens a property offers, written with one value in every mode. */
+function duplicateToken(ctx, report) {
+	const { config, modes } = ctx;
+	const reported = /* @__PURE__ */ new Set();
+	for (const property of config.list("style-property")) {
+		const key = property.path.split("/").pop() ?? property.path;
+		const byValue = /* @__PURE__ */ new Map();
+		const listed = stylePropEntries(config, property.path).map(({ value }) => value).filter((value) => config.resolve("token", value) !== void 0);
+		for (const token of listed) {
+			if (!ctx.own("token", token)) continue;
+			if (config.deprecated("token", token)) continue;
+			if (!SCALE_STEP.test(token.split("/").pop() ?? "")) continue;
+			const body = config.resolve("token", token)?.toJSON();
+			if (body?.value === void 0 || isRef(body.value) || typeof body.value === "object") continue;
+			const signature = modes.map(({ condition }) => String(resolveTokenValueUnder(config, token, condition)).trim().toLowerCase()).join("|");
+			byValue.set(signature, [...byValue.get(signature) ?? [], token]);
+		}
+		for (const [signature, tokens] of byValue) {
+			const [first, ...rest] = [...new Set(tokens)];
+			for (const token of rest) {
+				if (!first || reported.has(token)) continue;
+				reported.add(token);
+				report({
+					token,
+					prop: key,
+					value: signature.split("|")[0],
+					message: `\`${token}\` holds ${signature.split("|")[0]}, as \`${first}\` does${modes.length > 1 ? " in every mode" : ""}, and ${key} offers both.`,
+					suggestion: first
+				});
+			}
+		}
+	}
+}
+//#endregion
+export { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, CONFIG_LINT_RULES, lintReads, ruleSeverity };

package/dist/migrations/20261027205147_lint_ignore.d.ts

@@ -0,0 +1,6 @@
+/** `settings.lint.ignore`, the findings a system keeps on purpose, is additive: an optional list a
+ * config without one never had. Existing configs and draft patches retain their meaning.
+ * Retire this identity hop only when no supported artifact predates this schema. */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const LINT_IGNORE_VERSION = 20261027205147;
+export declare const lintIgnoreMigration: SchemaMigration;

package/dist/migrations/20261027205147_lint_ignore.js

@@ -0,0 +1,8 @@
+//#region src/migrations/20261027205147_lint_ignore.ts
+const LINT_IGNORE_VERSION = 20261027205147;
+const lintIgnoreMigration = {
+	version: LINT_IGNORE_VERSION,
+	up: (json) => json
+};
+//#endregion
+export { LINT_IGNORE_VERSION, lintIgnoreMigration };