@yahoo/uds-create-config 5.61.1 → 5.62.1

package/dist/lint/rules.d.ts

@@ -0,0 +1,337 @@
+import { ConfigLintContext, ConfigLintReport, LintLayer, LintValue, LintedComponent } from "./context.js";
+
+//#region src/lint/rules.d.ts
+declare const AUTHORING_LINT_GROUPS: {
+  readonly portability: {
+    readonly title: "Portability";
+    readonly about: "Values that reach a component only through code, so a team that links or extends your system can’t change them.";
+  };
+  readonly editability: {
+    readonly title: "Editability";
+    readonly 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.";
+  };
+  readonly maintainability: {
+    readonly title: "Maintainability";
+    readonly 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.";
+  };
+  readonly design: {
+    readonly title: "Design";
+    readonly 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.";
+  };
+  readonly compatibility: {
+    readonly title: "Compatibility";
+    readonly about: "Reliance on parts of the platform that are changing or internal, which a future update can break.";
+  };
+  readonly nursery: {
+    readonly title: "Nursery";
+    readonly 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. */
+    readonly defaultSeverity: "off";
+  };
+};
+type AuthoringLintGroup = keyof typeof AUTHORING_LINT_GROUPS;
+declare const AUTHORING_LINT_RULES: {
+  readonly 'inline-style-on-layer': {
+    readonly group: "portability";
+    readonly label: "Inline style";
+    readonly detects: "A style written directly on an element. It beats every rule, so no edit or override can change it.";
+    readonly fix: "move the values into the layer's style rule; a value the render works out becomes a `.states()` entry a rule keys on";
+  };
+  readonly 'token-variable-as-text': {
+    readonly group: "portability";
+    readonly label: "Token spelled as text";
+    readonly detects: "A token's CSS variable typed out by hand. Rename the token and this spot keeps the old name.";
+    readonly 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()`";
+  };
+  readonly 'variable-channel': {
+    readonly group: "portability";
+    readonly label: "Private CSS variable";
+    readonly detects: "A CSS variable the system sets and reads for itself, which overrides and linked systems can’t see.";
+    readonly 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";
+  };
+  readonly 'foreign-variable': {
+    readonly group: "portability";
+    readonly label: "Another package's variable";
+    readonly detects: "A CSS variable from outside the system. Nothing records that the system depends on it.";
+    readonly 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";
+  };
+  readonly 'runtime-style-read': {
+    readonly group: "editability";
+    readonly label: "Style read while running";
+    readonly detects: "A value measured in the browser at runtime, which the system's settings never see.";
+    readonly fix: "a rule, a modifier (`_reducedMotion`, `_rtl`), logical properties, or a `Token.ref` reader";
+  };
+  readonly 'render-data-attribute': {
+    readonly group: "editability";
+    readonly label: "Hidden state";
+    readonly detects: "A state the code sets for styling that the component doesn't declare, so Create can't show, force or preview it.";
+    readonly fix: "a value the render knows becomes a `.states()` entry; a value from a declared prop becomes a `when: { prop }` rule";
+  };
+  readonly 'internal-marker': {
+    readonly group: "compatibility";
+    readonly fixKind: "blocked";
+    readonly label: "Internal marker";
+    readonly detects: "A platform-internal attribute written by hand, which an update can change without notice.";
+    readonly fix: "use the public API that sets it; where none exists, report the gap rather than writing the marker";
+  };
+  readonly 'reserved-variable-name': {
+    readonly group: "portability";
+    readonly label: "Variable name a token could take";
+    readonly detects: "A hand-written CSS variable named like a token, which a future token could collide with.";
+    readonly fix: "rename it outside the generated prefixes, or make it a token so the build owns the name";
+  };
+  readonly 'override-copies-source': {
+    readonly group: "portability";
+    readonly fixKind: "auto";
+    readonly label: "Copied instead of extended";
+    readonly detects: "An override that copies a linked system's whole list to add to it, so later additions upstream never arrive.";
+    readonly 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";
+  };
+  readonly 'number-in-brackets': {
+    readonly reads: "both";
+    readonly group: "maintainability";
+    readonly label: "Number written as text";
+    readonly detects: "A number wrapped in brackets, like [240px], where the plain number works and reads better.";
+    readonly 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'`";
+    readonly fixKind: "auto";
+    readonly check: {
+      readonly value: typeof numberInBrackets;
+    };
+  };
+  readonly 'unused-token-group': {
+    readonly group: "nursery";
+    readonly label: "Unused token group";
+    readonly detects: "A group of tokens a property offers that nothing picks.";
+    readonly fix: "drop the group from the property's `values`, once the systems and apps in other repos that use it are checked too";
+  };
+  readonly 'duplicate-value-name': {
+    readonly group: "portability";
+    readonly label: "Two values, one name";
+    readonly detects: "A property that offers two values under the same name. Only one can ever be picked.";
+    readonly fix: "rename one of them, or drop the one that isn’t wanted, so each name means one value";
+  };
+  readonly 'render-default': {
+    readonly group: "editability";
+    readonly label: "Default hidden in code";
+    readonly detects: "A default value chosen in code rather than in the component's settings, so Create shows a different default than what renders.";
+    readonly fix: "move it into `.defaultProps({ … })`; a default the component already declares is deleted from the render";
+  };
+  readonly 'undeclared-prop': {
+    readonly group: "editability";
+    readonly label: "Property Create can't see";
+    readonly 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.";
+    readonly fix: "declare it in `.props()` with the type it takes; a handler is a forward to the layer that takes it";
+  };
+  readonly 'state-for-modifier': {
+    readonly group: "editability";
+    readonly label: "Hover tracked in code";
+    readonly detects: "Hover or focus tracked by code, where a built-in state would do the same and show in Create.";
+    readonly 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";
+  };
+  readonly 'forward-replaced-by-render': {
+    readonly group: "editability";
+    readonly label: "Content overridden in code";
+    readonly detects: "Content the component says goes to a layer, which the code replaces, so what you set doesn't show.";
+    readonly 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";
+  };
+  readonly 'glyph-in-render': {
+    readonly group: "editability";
+    readonly label: "Icon chosen in code";
+    readonly detects: "An icon the code picks, which Create can't show or swap.";
+    readonly fix: "set `name` in a rule on the icon layer, one per value of the prop or state that picks it";
+  };
+  readonly 'computed-config': {
+    readonly group: "editability";
+    readonly label: "Styles built by code";
+    readonly 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.";
+    readonly 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";
+  };
+  readonly 'restated-in-every-variant': {
+    readonly group: "maintainability";
+    readonly label: "Same value in every option";
+    readonly detects: "A value set identically under every option of a property. It never varies, so it belongs in the component's base style.";
+    readonly fix: "set it once, in the base rule";
+  };
+  readonly 'variant-passthrough': {
+    readonly group: "nursery";
+    readonly label: "One rule per option";
+    readonly detects: "A separate rule for each option that only passes the option along, so every new option needs a new rule.";
+    readonly fix: "forward the prop to the layer: `{ type: 'forward', target: '<layer>/<prop>' }`";
+  };
+  readonly 'no-op-modifier': {
+    readonly group: "maintainability";
+    readonly label: "State that changes nothing";
+    readonly detects: "A hover, focus or mode style that sets a value to what it already is.";
+    readonly 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";
+  };
+  readonly 'inherited-value-restated': {
+    readonly group: "maintainability";
+    readonly label: "Repeats its parent";
+    readonly detects: "A layer set to the same value it already gets from the layer around it.";
+    readonly 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";
+  };
+  readonly 'hand-forwarded-prop': {
+    readonly group: "editability";
+    readonly label: "Property passed along in code";
+    readonly 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.";
+    readonly 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";
+  };
+  readonly 'literal-matches-token': {
+    readonly reads: "both";
+    readonly group: "maintainability";
+    readonly label: "Value a token holds";
+    readonly detects: "A value typed by hand that one of your tokens already holds. Change the token and this spot is left behind.";
+    readonly fix: "use the token's name, as the style property takes it (`padding: '2'`)";
+    readonly check: {
+      readonly value: typeof literalMatchesToken;
+    };
+  };
+  readonly 'layer-bundle-split': {
+    readonly group: "editability";
+    readonly label: "Layer split apart in code";
+    readonly detects: "A layer's styling taken apart in code and partly applied elsewhere, so Create's edits land in the wrong place.";
+    readonly 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";
+  };
+  readonly 'context-carried-variant': {
+    readonly group: "editability";
+    readonly label: "Option passed down invisibly";
+    readonly detects: "A size or variant a part inherits from its parent behind the scenes, which Create doesn't know about.";
+    readonly 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";
+  };
+  readonly 'forced-prop-in-render': {
+    readonly group: "editability";
+    readonly label: "Value fixed in code";
+    readonly detects: "A style or option the code sets on a nested component, which Create can't change.";
+    readonly 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";
+  };
+  readonly 'ref-replaced-by-literal': {
+    readonly group: "portability";
+    readonly label: "Linked token copied";
+    readonly detects: "A linked token replaced by the value it already had, so it stops following the system it came from.";
+    readonly fix: "drop the override, or keep the ref the source has";
+  };
+  readonly 'shadowed-pin-directive': {
+    readonly group: "portability";
+    readonly label: "Option that does nothing";
+    readonly detects: "A linked system's setting for a component this system replaces with its own, so the setting has no effect.";
+    readonly fix: "delete the option, or move what it sets onto this system's own component";
+  };
+  readonly 'implicit-children': {
+    readonly group: "compatibility";
+    readonly label: "Content not declared";
+    readonly detects: "Content the component accepts without declaring it. The old way is going away, and Create can't see it until then.";
+    readonly fix: "declare it: `children: { type: 'slot' }`, or a forward to the layer the render places it in, `{ type: 'forward', target: '<layer>/children' }`";
+  };
+  readonly 'copied-component': {
+    readonly group: "nursery";
+    readonly label: "Copied component";
+    readonly detects: "A component whose styles are another's, word for word, so a change to one doesn't reach the other.";
+    readonly fix: "extend the other, `Component.ref('Other').extend({ … })`, and keep only what differs; two near copies extend one component both share";
+  };
+  readonly 'low-contrast': {
+    readonly group: "design";
+    readonly reads: "config";
+    readonly label: "Low contrast";
+    readonly detects: "Text that is hard to read against its background in light or dark mode. Text needs 4.5:1, icons 3:1.";
+    readonly fix: "pick a text or background token that clears 4.5:1 in every mode";
+    readonly check: {
+      readonly layer: typeof lowContrast;
+    };
+  };
+  readonly 'near-token': {
+    readonly group: "design";
+    readonly reads: "config";
+    readonly label: "Almost a token";
+    readonly 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.";
+    readonly fix: "use the token when it was meant; if the value is on purpose, it may belong on the scale";
+    readonly check: {
+      readonly value: typeof nearToken;
+    };
+  };
+  readonly 'fixed-in-dark-mode': {
+    readonly group: "design";
+    readonly reads: "config";
+    readonly label: "Same in dark mode";
+    readonly detects: "A color that doesn't change in dark mode while the rest of the component does.";
+    readonly fix: "use a token that has a dark value, or give this one a `_dark` value";
+    readonly check: {
+      readonly component: typeof fixedInDarkMode;
+    };
+  };
+  readonly 'small-tap-target': {
+    readonly group: "design";
+    readonly reads: "config";
+    readonly label: "Small tap target";
+    readonly 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.";
+    readonly fix: "make it at least that size each way, or grow its hit area with padding";
+    readonly check: {
+      readonly layer: typeof smallTapTarget;
+    };
+  };
+  readonly 'duplicate-token': {
+    readonly group: "design";
+    readonly reads: "config";
+    readonly label: "Two tokens, one value";
+    readonly detects: "Two steps on a scale that hold the same value, so nobody can tell which to pick.";
+    readonly fix: "keep one, or make the other a reference to it (`Token.ref(…)`) so the two are one decision";
+    readonly check: {
+      readonly system: typeof duplicateToken;
+    };
+  };
+  readonly 'wildcard-forward': {
+    readonly group: "nursery";
+    readonly label: "Accepts anything";
+    readonly detects: "A component that passes along every property it gets. It will soon accept only what it declares.";
+    readonly 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)";
+  };
+};
+/**
+ * A config check, at the level it reads. The run walks the system once and calls each check with what
+ * it already resolved, so a check names a condition and walks nothing:
+ *
+ * - `value`: every style value a component of the system's own writes;
+ * - `layer`: each layer of each variant cell, with the styles it paints by what they do;
+ * - `component`: each of the system's own components;
+ * - `system`: the system once, for what spans components (its tokens).
+ */
+interface ConfigLintCheck {
+  value?(ctx: ConfigLintContext, value: LintValue, report: ConfigLintReport): void;
+  layer?(ctx: ConfigLintContext, layer: LintLayer, report: ConfigLintReport): void;
+  component?(ctx: ConfigLintContext, component: LintedComponent, report: ConfigLintReport): void;
+  system?(ctx: ConfigLintContext, report: ConfigLintReport): void;
+}
+type AuthoringLintRule = keyof typeof AUTHORING_LINT_RULES;
+type LintReads = 'code' | 'config' | 'both';
+/** What a rule checks; see `reads` on {@link AUTHORING_LINT_RULES}. */
+declare const lintReads: (rule: AuthoringLintRule) => LintReads;
+/** The rules whose `reads` takes in the config. */
+type ConfigReadLintRule = { [K in AuthoringLintRule]: (typeof AUTHORING_LINT_RULES)[K] extends {
+  reads: 'config' | 'both';
+} ? K : never }[AuthoringLintRule];
+/** The rules that read the config, which `lintConfig` runs wherever a config is loaded. */
+declare const CONFIG_LINT_RULES: ConfigReadLintRule[];
+type AuthoringLintSeverity = 'off' | 'warn' | 'error';
+/**
+ * How a finding gets fixed: `auto`, `uds lint --fix` rewrites it; `agent`, it needs judgment, which
+ * `--reporter json` hands to a person or an agent; `blocked`, it waits on a platform feature the
+ * finding names.
+ */
+type AuthoringLintFix = 'auto' | 'agent' | 'blocked';
+/** A rule's severity as `settings.lint.rules` sets it: its own entry, else its group's, else the
+ *  group's default. */
+declare function ruleSeverity(rule: AuthoringLintRule, severities: Readonly<Record<string, AuthoringLintSeverity>>): AuthoringLintSeverity;
+/** literal-matches-token: the same text a token holds. */
+declare function literalMatchesToken(ctx: ConfigLintContext, value: LintValue, report: ConfigLintReport): void;
+/** number-in-brackets: a property that reads bare numbers, written in brackets. */
+declare function numberInBrackets(ctx: ConfigLintContext, value: LintValue, report: ConfigLintReport): void;
+/** near-token: off a token by a pixel or so. */
+declare function nearToken(ctx: ConfigLintContext, value: LintValue, report: ConfigLintReport): void;
+/** fixed-in-dark-mode: colors that hold still while the component's others change. */
+declare function fixedInDarkMode(ctx: ConfigLintContext, component: LintedComponent, report: ConfigLintReport): void;
+/** low-contrast: a layer's text over its background, in each mode. */
+declare function lowContrast(ctx: ConfigLintContext, layer: LintLayer, report: ConfigLintReport): void;
+/** small-tap-target: the root of something you press, under the platform's minimum. */
+declare function smallTapTarget(ctx: ConfigLintContext, layer: LintLayer, report: ConfigLintReport): void;
+/** duplicate-token: two tokens a property offers, written with one value in every mode. */
+declare function duplicateToken(ctx: ConfigLintContext, report: ConfigLintReport): void;
+//#endregion
+export { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, AuthoringLintFix, AuthoringLintGroup, AuthoringLintRule, AuthoringLintSeverity, CONFIG_LINT_RULES, ConfigLintCheck, ConfigReadLintRule, LintReads, lintReads, ruleSeverity };