stillwind 0.0.0 → 0.1.0-rc.0

package/docs/lints/prefer-canonical-utilities.md

@@ -0,0 +1,69 @@
+---
+title: "prefer-canonical-utilities"
+description: "Suggests standard utility spellings and combines equivalent utilities."
+---
+
+# prefer-canonical-utilities
+
+This rule suggests standard spellings, such as `px-4` for `px-[16px]`. It also
+removes unnecessary spaces from arbitrary values, simplifies variants and modifiers,
+and replaces legacy Tailwind spellings. Suggestions use your active theme and custom
+definitions.
+
+Within one string or one CSS `@apply` statement, it can combine utilities such as
+`w-4 h-4` into `size-4`. Utilities must have the same variants and importance.
+
+## Reported
+
+```tsx
+style("px-[16px]");
+```
+
+> prefer-canonical-utilities: replace `px-[16px]` with `px-4`
+> 
+> Example:1:8
+
+## Fixed
+
+```tsx
+style("px-4");
+```
+
+## How to fix
+
+Use the suggested form. The automatic fix applies it.
+
+## Options
+
+`pxToRem` compares `px` values with `rem` values by using `rootFontSize`. With the
+default root size of 16px, `px-[16px]` matches `px-4`, which is `1rem`. Turn the
+option off if your documents use another root size and you have not set
+`rootFontSize`.
+
+`collapse` controls whether several utilities can share one replacement. It defaults
+to `true`. Set it to `false` to keep each utility separate.
+
+`logicalToPhysical` allows logical properties to match physical properties under
+horizontal, left-to-right writing. It defaults to `false`. Enable it only when that
+writing mode is appropriate for your document.
+
+`preserveSpecificity` defaults to `true`. Set it to `false` to allow Tailwind's ancestor
+variant migrations, such as `[p_&]` to `in-[p]`. That replacement uses `:where()` and
+reduces specificity.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+| Option | Default |
+| --- | --- |
+| `pxToRem` | `true` |
+| `collapse` | `true` |
+| `logicalToPhysical` | `false` |
+| `preserveSpecificity` | `true` |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/prefer-direct-styling.md

@@ -0,0 +1,47 @@
+---
+title: "prefer-direct-styling"
+description: "Reports a selector variant that styles another element, such as [&_button]:."
+---
+
+# prefer-direct-styling
+
+This rule reports a selector variant that styles another element from the
+current one, such as `[&_button]:` on a parent. The styles of the button then
+live in the parent, so reading the button does not show them. The `stylistic`
+preset enables this rule.
+
+## Reported
+
+```tsx
+const toolbar = style("flex gap-2 [&_button]:p-4");
+```
+
+> prefer-direct-styling: variant selector `& button` styles another element. Attach these styles directly to that element
+> 
+> Example:1:35
+
+## Fixed
+
+```tsx
+const toolbar = style("flex gap-2");
+const button = style("p-4");
+```
+
+## How to fix
+
+- Give the styles to the element itself with its own `style()` call, as in the
+  example.
+- If the element comes from markup that you cannot change, such as rendered
+  Markdown, keep the selector and add a
+  [suppression comment](../configuration.md#suppression-comments) with the
+  reason.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | off |
+| `stylistic` | warn |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/prefer-explicit-nesting-selector.md

@@ -0,0 +1,42 @@
+---
+title: "prefer-explicit-nesting-selector"
+description: "Reports a custom variant selector without &, which matches descendants."
+---
+
+# prefer-explicit-nesting-selector
+
+This rule reports a `@custom-variant` selector without `&`. Without `&`, the
+selector matches descendants of the element, not the element itself. In the
+example, `hocus:` would match hovered elements inside the element.
+
+## Reported
+
+```css
+@custom-variant hocus (:hover);
+```
+
+> prefer-explicit-nesting-selector: variant selector `:hover` is relative to `&` and means `& :hover`; write the `&`, or add `scope(document)` to the definition to select a document-level element
+> 
+> Example:1:24
+
+## Fixed
+
+```css
+@custom-variant hocus (&:hover);
+```
+
+## How to fix
+
+- Add `&` where the element belongs in the selector, as in the example.
+- If the variant should match descendants, write that explicitly, such as
+  `(& :hover)`.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/prefer-logical-properties.md

@@ -0,0 +1,49 @@
+---
+title: "prefer-logical-properties"
+description: "Reports a physical property that has a logical form, such as ml-4 for ms-4."
+---
+
+# prefer-logical-properties
+
+This rule reports a utility for a physical property that has a logical form, such
+as `ml-4` (left) for `ms-4` (start). A logical property follows the writing
+direction, so the layout also works in right-to-left languages. The `stylistic`
+preset enables this rule.
+
+## Reported
+
+```tsx
+style("ml-4");
+```
+
+> prefer-logical-properties: prefer a logical declaration for `margin-left: calc(var(--spacing) * 4)`
+> 
+> Example:1:8
+
+## Fixed
+
+```tsx
+style("ms-4");
+```
+
+## How to fix
+
+- If the margin separates the element from the content before it, use the
+  logical form, as in the example.
+- If the side must stay on the left in every language, such as for an icon that
+  points left, keep the physical form and add a
+  [suppression comment](../configuration.md#suppression-comments).
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | off |
+| `stylistic` | warn |
+
+| Option | Default |
+| --- | --- |
+| `checkImplementation` | `false` |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/prefer-sorted-utilities.md

@@ -0,0 +1,46 @@
+---
+title: "prefer-sorted-utilities"
+description: "Reports utilities that are not in sorted order."
+---
+
+# prefer-sorted-utilities
+
+This rule reports utilities that are not in the order that `stillwind fmt` uses.
+The order does not change the CSS. A consistent order makes utilities easier to
+read and diffs smaller. The `stylistic` preset enables this rule.
+
+## Reported
+
+```tsx
+style("px-4 flex");
+```
+
+> prefer-sorted-utilities: utilities are not in compiler order
+> 
+> Example:1:8
+
+## Fixed
+
+```tsx
+style("flex px-4");
+```
+
+## How to fix
+
+Run `stillwind fmt`, or `stillwind lint --fix` with this rule enabled. The editor
+also sorts on save with `source.sort.stillwind`.
+
+`stillwind fmt` sorts even when this rule is off. To stop all sorting, set
+`sort: false`. See [Sorting](../configuration.md#sorting).
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | off |
+| `stylistic` | warn |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.
+
+The CLI and the editor report this rule only when they analyze the whole project.

package/docs/lints/prefer-typed-relationships.md

@@ -0,0 +1,48 @@
+---
+title: "prefer-typed-relationships"
+description: "Reports group-* and peer-* variants that a ref can replace."
+---
+
+# prefer-typed-relationships
+
+This rule reports `group-*` and `peer-*` variants. They connect elements through
+the class names `group` and `peer`, so any element with the same class can
+match, and nothing checks a misspelled name. A ref connects the elements through a
+variable instead. The `stylistic` preset enables this rule.
+
+## Reported
+
+```tsx
+style("group-hover:text-red-500");
+```
+
+> prefer-typed-relationships: Tailwind relationship utility `group-hover:text-red-500` is forbidden; use style.ref() and specify shared scopes with in()
+> 
+> Example:1:8
+
+## Fixed
+
+```tsx
+const card = style.ref("card");
+const container = style(card);
+const title = style({ [card("hover")]: "text-red-500" });
+```
+
+## How to fix
+
+- Replace `group` with a ref on the parent, and `group-hover:` with a condition on
+  that ref, as in the example.
+- Replace `peer` with a ref on the sibling, and use
+  [`.in()`](../macros/ref/in.md) with a ref on a shared ancestor.
+
+See [Element relationships](../guides/element-relationships.md).
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | off |
+| `stylistic` | warn |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/prefer-typed-variables.md

@@ -0,0 +1,43 @@
+---
+title: "prefer-typed-variables"
+description: "Reports a custom property without a type in a utility that accepts several types."
+---
+
+# prefer-typed-variables
+
+This rule reports a custom property without a type in a utility that accepts
+several types. For example, `text-*` sets a color or a font size, so
+`text-(--brand)` does not show which one you mean. The `stylistic` preset enables
+this rule.
+
+## Reported
+
+```tsx
+style("text-(--brand)");
+```
+
+> prefer-typed-variables: `text-(--brand)` has no type hint, so it uses the `color` definition; write `text-(color:--brand)` to state the type
+> 
+> Example:1:13
+
+## Fixed
+
+```tsx
+style("text-(color:--brand)");
+```
+
+## How to fix
+
+Add the type that the custom property holds, such as `color:` in the example, or
+`length:` for a font size. The type only chooses the meaning of the utility. It
+does not check the value that the property receives at runtime.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | off |
+| `stylistic` | warn |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/prefer-variant-directive.md

@@ -0,0 +1,59 @@
+---
+title: "prefer-variant-directive"
+description: "Reports a condition in your stylesheet that a named variant can replace."
+---
+
+# prefer-variant-directive
+
+This rule reports a condition in a rule of your stylesheet, such as an `@media`
+query, that a variant of your theme expresses with the same meaning. The named
+variant keeps the stylesheet in sync when the theme changes the breakpoint. The
+`stylistic` preset enables this rule.
+
+## Reported
+
+```css
+.card {
+  @media (width >= 48rem) {
+    display: flex;
+  }
+}
+```
+
+> prefer-variant-directive: `@media (width >= 48rem)` applies the same condition as variant `md`; write `@variant md`
+> 
+> Example:2:3
+
+## Fixed
+
+```css
+.card {
+  @variant md {
+    display: flex;
+  }
+}
+```
+
+## How to fix
+
+Replace the condition with `@variant` and the name of the variant, as in the
+example. The automatic fix applies it.
+
+## Options
+
+`pxToRem` treats `px` and `rem` in media queries as equal at 16px per `rem`. With
+it, `@media (width >= 768px)` also matches `md`.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | off |
+| `stylistic` | warn |
+
+| Option | Default |
+| --- | --- |
+| `pxToRem` | `false` |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/redundant-variant.md

@@ -0,0 +1,50 @@
+---
+title: "redundant-variant"
+description: "Reports a variant that adds no condition, such as hover:hover:."
+---
+
+# redundant-variant
+
+This rule reports a variant that adds no condition, such as a second `hover:` in
+`hover:hover:`. It also reports a variant that another variant in the stack
+already implies. With the default breakpoints, `sm:` is redundant in `sm:md:`
+because every width that matches `md:` also matches `sm:`.
+
+## Reported
+
+```tsx
+style("hover:hover:p-4");
+style("sm:md:p-4");
+```
+
+> redundant-variant: variant `hover` repeats the earlier `hover` and has no effect
+> 
+> Example:1:14
+
+> redundant-variant: variant `sm` has no effect because `md` implies its condition
+> 
+> Example:2:8
+
+## Fixed
+
+```tsx
+style("hover:p-4");
+style("md:p-4");
+```
+
+## How to fix
+
+Remove the extra variant, and keep the others. The automatic fix removes it.
+
+Variants that can never match together are reported by
+[unsatisfiable-variants](unsatisfiable-variants.md) instead.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/repeated-nesting-selector.md

@@ -0,0 +1,59 @@
+---
+title: "repeated-nesting-selector"
+description: "Reports a selector that repeats & to relate two elements, such as [&+&]."
+---
+
+# repeated-nesting-selector
+
+This rule reports a selector variant that repeats `&`, such as `[&+&]:`, to relate
+two elements. `&` stands for the generated class of the style, so the selector
+matches any two elements that share the style. When the style is shared or used
+as a base, it can match pairs that you did not mean.
+
+## Reported
+
+```tsx
+function Items({ labels }: { labels: string[] }) {
+  return (
+    <div>
+      {labels.map((label) => (
+        <div {...style("[&+&]:mt-4")}>{label}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+> repeated-nesting-selector: `&+&` uses `&` more than once, so it matches by generated class identity; relate elements with style.ref()
+> 
+> Example:5:25
+
+## Fixed
+
+```tsx
+function Items({ labels }: { labels: string[] }) {
+  return (
+    <div {...style("flex flex-col gap-4")}>
+      {labels.map((label) => (
+        <div>{label}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## How to fix
+
+- To space items in a list, put `gap` on the list, as in the example.
+- To style an element from the state of a sibling, use refs with
+  [`.in()`](../macros/ref/in.md).
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/runtime-condition-requires-css-if.md

@@ -0,0 +1,59 @@
+---
+title: "runtime-condition-requires-css-if"
+description: "Reports a runtime CSS condition that needs the useCssIf setting."
+---
+
+# runtime-condition-requires-css-if
+
+This rule reports a runtime CSS condition, such as `if(--state:active):`, that
+the compiler can only express with the native CSS `if()` function. The project
+does not enable it, so the utility produces no CSS.
+
+## Reported
+
+```tsx
+style("if(--state:active):block");
+```
+
+> runtime-condition-requires-css-if: `if(--state:active):block` cannot be lowered: custom-property value comparisons require useCssIf: true
+> 
+> Example:1:8
+
+## Fixed
+
+```ts title="stillwind.config.ts"
+import { defineConfig } from "stillwind/config";
+
+export default defineConfig({
+  projects: [
+    {
+      css: "./src/stillwind.css",
+      files: ["src/**/*.{ts,tsx}"],
+      useCssIf: true,
+    },
+  ],
+});
+```
+
+```tsx
+style("if(--state:active):block");
+```
+
+## How to fix
+
+- If the browsers that you support implement CSS `if()`, set `useCssIf: true` in
+  the project, as in the example. Keep the condition on the custom property.
+- Otherwise, represent the state with an attribute and use an attribute variant.
+  That requires changing the code that sets the state as well.
+
+See [Configuration](../configuration.md#generated-css).
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | deny |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/split-view-transition-class.md

@@ -0,0 +1,47 @@
+---
+title: "split-view-transition-class"
+description: "Reports view transitions split across separate style() calls."
+---
+
+# split-view-transition-class
+
+This rule reports view transitions that reach one element through separate
+`style()` calls, such as a base style and the call that receives it. Each call
+sets the whole `view-transition-class` list, so one list replaces the other.
+
+## Reported
+
+```tsx
+const first = style.viewTransition({ old: "duration-150" });
+const second = style.viewTransition({ new: "duration-150" });
+const base = style(first.for("card"));
+style(base, second);
+```
+
+> split-view-transition-class: view-transition-class is one property: this call's list replaces the one its composed base declares, so declare the transitions in one call
+> 
+> Example:4:1
+
+## Fixed
+
+```tsx
+const first = style.viewTransition({ old: "duration-150" });
+const second = style.viewTransition({ new: "duration-150" });
+style(first, second.for("card"));
+```
+
+## How to fix
+
+Pass every transition of the element to the same `style()` call, with one
+`.for()`, as in the example. You can still store and share the transition
+definitions themselves.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/suspending-macro-argument.md

@@ -0,0 +1,46 @@
+---
+title: "suspending-macro-argument"
+description: "Reports await, yield, or import() inside an argument of style() or another macro."
+---
+
+# suspending-macro-argument
+
+This rule reports `await`, `yield`, or a dynamic `import()` inside an argument of
+`style()` or another macro. The compiler can move or skip argument expressions,
+so the code would not wait or load where you wrote it.
+
+## Reported
+
+```tsx
+async function props() {
+  return style({ "--x": await Promise.resolve(1) });
+}
+```
+
+> suspending-macro-argument: evaluate await, yield, and dynamic imports outside macro arguments, then pass their values
+> 
+> Example:2:25
+
+## Fixed
+
+```tsx
+async function props() {
+  const value = await Promise.resolve(1);
+  return style({ "--x": value });
+}
+```
+
+## How to fix
+
+Wait for the value before the call, store it in a variable, and pass the
+variable, as in the example.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | deny |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.