stillwind 0.0.0 → 0.1.0-rc.0

package/docs/lints/unknown-utility.md

@@ -0,0 +1,47 @@
+---
+title: "unknown-utility"
+description: "Reports a utility or theme value that your stylesheet does not define."
+---
+
+# unknown-utility
+
+This rule reports a utility that your stylesheet does not define. It also reports
+a known utility with a theme value that does not exist, such as `bg-red-999`. The
+utility produces no CSS.
+
+## Reported
+
+```tsx
+style("bg-red-95O");
+```
+
+> unknown-utility: `bg` has no value `red-95O`; did you mean `bg-red-950`?
+> 
+> Example:1:11
+
+## Fixed
+
+```tsx
+style("bg-red-950");
+```
+
+## How to fix
+
+- Check the spelling against the theme. In the example, the last character is
+  the letter `O` instead of zero. The intended token is `--color-red-950`.
+- To use a value that the theme does not have, add a token to your stylesheet,
+  such as `--color-red-999` in `@theme`, or define the utility with `@utility`.
+- For a class that another stylesheet defines, pass it in a `class` field, such as
+  `style({ class: "external-card" })`.
+
+[Built-in utilities](../utilities.md) looks up the utilities of the default theme.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/unknown-variant.md

@@ -0,0 +1,42 @@
+---
+title: "unknown-variant"
+description: "Reports a variant that your stylesheet does not define."
+---
+
+# unknown-variant
+
+This rule reports a variant that your stylesheet does not define, such as a
+misspelled `hovr:`. The condition never matches, so the utilities under it never
+apply.
+
+## Reported
+
+```tsx
+style("hovr:p-4");
+```
+
+> unknown-variant: unknown variant `hovr`; did you mean `hover:p-4`?
+> 
+> Example:1:8
+
+## Fixed
+
+```tsx
+style("hover:p-4");
+```
+
+## How to fix
+
+- Correct the spelling of the variant.
+- To use a variant of your own, define it with `@custom-variant` in your
+  stylesheet.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/unsatisfiable-variants.md

@@ -0,0 +1,42 @@
+---
+title: "unsatisfiable-variants"
+description: "Reports variants that can never match together, such as portrait:landscape:."
+---
+
+# unsatisfiable-variants
+
+This rule reports stacked variants that can never match at the same time.
+Stacked variants must all match, and a viewport cannot be in portrait and
+landscape orientation at once. The utility never applies.
+
+## Reported
+
+```tsx
+style("portrait:landscape:p-4");
+```
+
+> unsatisfiable-variants: variants `portrait:landscape` never match because `@media (orientation: portrait)` and `@media (orientation: landscape)` exclude each other
+> 
+> Example:1:8
+
+## Fixed
+
+```tsx
+style("portrait:p-4 landscape:p-4");
+```
+
+## How to fix
+
+- To apply the utility in either case, write one utility for each variant, as in
+  the example. When the cases cover every situation, drop the variants: `p-4`.
+- To apply the utility in one case only, keep the variant for that case.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[Configure lint](../configuration.md#lint) to change the severity or options.

package/docs/lints/unused-lint-suppression.md

@@ -0,0 +1,57 @@
+---
+title: "unused-lint-suppression"
+description: "Reports a suppression comment that suppresses no finding."
+---
+
+# unused-lint-suppression
+
+This rule reports a suppression comment that suppresses no finding, for example
+because the code was fixed after the comment was added. The comment would hide a
+future finding that nobody has reviewed. The `strict` preset enables this rule.
+
+## Configuration
+
+```json
+{
+  "lint": {
+    "rules": {
+      "unknown-utility": "warn",
+      "unused-lint-suppression": "warn"
+    }
+  }
+}
+```
+
+## Reported
+
+```tsx
+// swlint-disable-next-line unknown-utility
+style("p-4");
+```
+
+> unused-lint-suppression: lint suppression for `unknown-utility` suppresses no enabled findings
+> 
+> Example:1:29
+
+## Fixed
+
+```tsx
+style("p-4");
+```
+
+## How to fix
+
+Remove the comment, as in the example. If the rule should still report the line,
+check that the comment is on the right line and names the right rule.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | off |
+| `strict` | deny |
+| `stylistic` | off |
+
+[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/unverified-style-base.md

@@ -0,0 +1,64 @@
+---
+title: "unverified-style-base"
+description: "Reports a base style whose source the CLI cannot find from its type."
+---
+
+# unverified-style-base
+
+This rule reports a base style whose type does not show which `style()` call
+created it, such as a value declared as `ReturnType<typeof style>`. The compiler
+cannot find the CSS of the base, so it cannot order the later utilities after it.
+
+## Project files
+
+```ts title="globals.d.ts"
+declare module "virtual:styles" {
+  import { style } from "stillwind/react";
+
+  export const base: ReturnType<typeof style>;
+}
+```
+
+```ts title="styles.ts"
+import { style } from "stillwind/react";
+
+export const base = style("rounded-md");
+```
+
+## Reported
+
+```tsx
+import { base } from "virtual:styles";
+
+export const props = style(base, "p-4");
+```
+
+> unverified-style-base: the style base cannot be identified, so its CSS may follow this call's CSS
+> 
+> Example:3:28
+
+## Fixed
+
+```tsx
+import { base } from "./styles";
+
+export const props = style(base, "p-4");
+```
+
+## How to fix
+
+- Import the base from the source module that calls `style()`, as in the example.
+- Keep the type that TypeScript infers when you export a style. A type annotation
+  such as `ReturnType<typeof style>` hides the source.
+
+## Rule settings
+
+| Preset | Severity |
+| --- | --- |
+| `recommended` | warn |
+| `strict` | deny |
+| `stylistic` | off |
+
+[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/macros/anchor-scope.md

@@ -0,0 +1,90 @@
+---
+title: "style.anchorScope()"
+description: "Limit where an anchor name is visible, so that each component instance uses its own anchor."
+---
+
+# style.anchorScope()
+
+`style.anchorScope(scope)` sets `anchor-scope` on an element. Inside that
+element, a positioned element finds only the anchors that are also inside it.
+Use it when a component with an anchor renders more than once on a page.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const trigger = style.ref("trigger");
+export const provider = style(trigger, trigger.asAnchor());
+export const scope = style(style.anchorScope([trigger]));
+export const popover = style("absolute", trigger.positionAnchor(), "top-[anchor(bottom)]");
+```
+
+### Compiled code
+
+```ts
+const trigger = undefined;
+export const provider = {className:"sw_im2u7 sw_trigger_xnn7w"};
+export const scope = {className:"sw_tcyj3"};
+export const popover = {className:"sw_vqbik"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_im2u7:where(.sw_trigger_xnn7w) {
+  anchor-name: --sw-a-trigger-xnn7w;
+}
+
+.sw_tcyj3 {
+  anchor-scope: --sw-a-trigger-xnn7w;
+}
+
+.sw_vqbik {
+  position-anchor: --sw-a-trigger-xnn7w;
+  position: absolute;
+  top: anchor(bottom);
+}
+```
+
+Three elements work together:
+
+| Element     | Call                                   | Sets              |
+| ----------- | -------------------------------------- | ----------------- |
+| The anchor  | `style(trigger, trigger.asAnchor())`   | `anchor-name`     |
+| An ancestor | `style(style.anchorScope([trigger]))`  | `anchor-scope`    |
+| The popover | `style(trigger.positionAnchor(), ...)` | `position-anchor` |
+
+Put the scope on the ancestor that contains one anchor and its popover.
+
+## Inputs
+
+| Scope            | Effect                                |
+| ---------------- | ------------------------------------- |
+| An array of refs | Limits the anchor names of those refs |
+| `"all"`          | Limits every anchor name              |
+| `"none"`         | Sets `anchor-scope: none`             |
+
+Write the array or keyword directly in the call. When a variable in the array
+can hold one of several refs, the scope includes every ref that it can hold.
+
+An empty array sets nothing, and repeated refs add nothing.
+[ineffective-anchor-scope](../lints/ineffective-anchor-scope.md) reports both.
+
+`style.anchorScope()` only sets the CSS property. It does not attach a ref, it
+does not create an anchor name, and it does not affect `.in()` conditions.
+
+You can also set the scope on the anchor itself with
+`trigger.asAnchor(scope)`. See [ref.asAnchor()](ref/as-anchor.md).
+
+## Generated code
+
+The compiler turns the scope into generated anchor names or the keyword. When
+it knows every ref, no JavaScript reads the refs at runtime. Stillwind does not
+position elements with JavaScript; the browser's CSS anchor positioning does.
+
+See [Element relationships](../guides/element-relationships.md#position-an-element-at-an-anchor)
+for a complete example.

package/docs/macros/css.md

@@ -0,0 +1,68 @@
+---
+title: "style.css()"
+description: "Compile utilities into a CSS string that you place yourself, such as in a shadow root."
+---
+
+# style.css()
+
+`style.css(...rules, options?)` compiles utilities into a CSS string. Unlike
+`style()`, it adds nothing to the page's stylesheet. You decide where the string
+goes, such as a shadow root.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+export const css = style.css("p-4 text-blue-600", {
+  selector: ":host",
+});
+```
+
+### Compiled code
+
+```ts
+export const css = "/*! stillwind v0.0.0 | MIT License | https://stillwind.dev */\n/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */\n:where(:root, :host){--color-blue-600:oklch(54.6% 0.245 262.881);--spacing:0.25rem;}:host{padding:calc(var(--spacing) * 4);}:host{color:var(--color-blue-600);}";
+```
+
+### Generated CSS
+
+This macro adds no CSS to the stylesheet.
+
+## Inputs
+
+`rules` accepts utility strings, arrays, objects with variant keys, and `false`,
+`null`, or `undefined`. All of them must be known at build time. Runtime
+conditions, refs, `class` fields, custom properties, and stored `style()`
+results are not accepted, and [invalid-css-input](../lints/invalid-css-input.md)
+reports them.
+
+The last argument can be an options object literal:
+
+| Option     | Value                                                                              |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `selector` | The selector that utilities without their own selector style, such as `:host`      |
+| `template` | The name of an `@stillwind-css-template` in your stylesheet; defaults to `default` |
+
+A variant that sets its own selector, such as `host:` or `[button]:`, keeps that
+selector. A utility without `selector` and without such a variant produces no
+CSS, and [missing-document-target](../lints/missing-document-target.md) reports it.
+
+## Output
+
+The compiler replaces the call with a string literal at build time. No CSS
+compiler runs in the browser.
+
+The string contains the theme values, keyframes, and other supporting CSS that
+the template and the utilities need. It never contains the preflight reset.
+
+Add the string to the page yourself, for example with
+`CSSStyleSheet.replaceSync()` and a shadow root's `adoptedStyleSheets`. The
+results in [Built-in utilities](../utilities.md) leave out the supporting CSS,
+so they cannot replace this string.
+
+To add all styles of a module to a shadow root, including the preflight reset,
+import them from `stillwind/module-css` instead. See
+[Web Components](../guides/web-components.md).

package/docs/macros/cva.md

@@ -0,0 +1,153 @@
+---
+title: "style.cva()"
+description: "Create a factory that selects compiled styles by option, with the configuration of class-variance-authority."
+---
+
+# style.cva()
+
+`style.cva(base?, config?)` creates a factory with the configuration format of
+`cva` from class-variance-authority. The compiler generates the CSS for every
+option at build time. Calling the factory selects the compiled classes for the
+chosen options and returns props for an element.
+
+`style.cva()` exists mainly to migrate existing CVA components. For new
+components, see [Reusable styles](../guides/reusable-styles.md).
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+export const button = style.cva("inline-flex rounded-md", {
+  variants: {
+    size: {
+      small: "px-2 py-1",
+      large: "px-4 py-2",
+    },
+  },
+  defaultVariants: {
+    size: "small",
+  },
+  compoundVariants: [
+    {
+      size: "large",
+      class: "font-medium",
+    },
+  ],
+});
+
+export const props = button({ size: "large" });
+```
+
+### Compiled code
+
+```ts
+import { stillwindCva } from "stillwind/runtime/class-name-object";
+
+export const button = stillwindCva("sw_ilpwh", {
+  variants: {
+    size: {
+      small: "sw_h1m4c",
+      large: "sw_8bi9g",
+    },
+  },
+  defaultVariants: {
+    size: "small",
+  },
+  compoundVariants: [
+    {
+      size: "large",
+      class: "sw_xlk4i",
+    },
+  ],
+});
+
+export const props = button({ size: "large" });
+```
+
+### Generated CSS
+
+
+```css
+.sw_ilpwh {
+  display: inline-flex;
+  border-radius: var(--radius-md);
+}
+
+.sw_h1m4c {
+  padding-inline: calc(var(--spacing) * 2);
+  padding-block: calc(var(--spacing) * 1);
+}
+
+.sw_8bi9g {
+  padding-inline: calc(var(--spacing) * 4);
+  padding-block: calc(var(--spacing) * 2);
+}
+
+.sw_xlk4i {
+  --tw-font-weight: var(--font-weight-medium);
+  font-weight: var(--font-weight-medium);
+}
+```
+
+## Configuration
+
+Write the configuration as an object literal in the call:
+
+| Field              | Value                                                            |
+| ------------------ | ---------------------------------------------------------------- |
+| `variants`         | Each option name maps each value to a style                      |
+| `defaultVariants`  | The value that each option uses when the call passes `undefined` |
+| `compoundVariants` | Entries that add `class` when every listed option matches        |
+
+`class` and `className` cannot be option names, because the factory uses them
+for classes from other stylesheets. An option with the values `true` and
+`false` accepts booleans.
+
+Use `VariantProps<typeof button>` from your framework's entrypoint to type the
+options.
+
+## Style values
+
+The base and each option value accept utility strings, arrays, objects with
+variant keys, `true`, `false`, `null`, `undefined`, and custom properties.
+
+They do not accept `&&`, ternaries, stored `style()` results, refs, animations,
+or `class` fields. To choose a style at runtime, pass a different option to the
+factory. [invalid-cva-input](../lints/invalid-cva-input.md) reports these
+values, and [invalid-cva-config](../lints/invalid-cva-config.md) reports a
+malformed configuration.
+
+A custom property value can be an expression. The factory evaluates it once,
+when the factory is created. Custom properties stay in the inline style, so a
+later option can replace them.
+
+## Calling the factory
+
+| Option value | Result                                |
+| ------------ | ------------------------------------- |
+| `undefined`  | Uses the value from `defaultVariants` |
+| `null`       | Adds nothing for that option          |
+| A value      | Adds the style of that value          |
+
+The result combines, in order: the base, the selected values in the order of
+the keys of `variants`, every matching compound variant in array order, and the
+`class` or `className` from the call. The option values are not passed to the
+element. Each call returns a new props object.
+
+The factory does not merge utilities at runtime. When two selected styles set
+the same property, the compiler's CSS order decides which one wins.
+
+The props that the factory returns cannot be passed to `style()` as a base.
+
+## Generated code
+
+The compiler creates the factory with `stillwindCva` from the framework runtime,
+together with the compiled class names. Factory calls stay ordinary JavaScript.
+The development build checks the selected values and the classes from other
+stylesheets.
+
+See [Migrating from Tailwind CSS](../guides/migrating-from-tailwind.md#cva) to
+convert existing `cva` calls.

package/docs/macros/index.md

@@ -0,0 +1,30 @@
+---
+title: "Macro reference"
+description: "Find the Stillwind API for a task, and read its accepted inputs and generated code."
+---
+
+# Macro reference
+
+Stillwind's API consists of macros: functions that the compiler replaces with
+generated code at build time. Each page lists the inputs that the macro accepts,
+and it shows the generated JavaScript and CSS for its examples.
+
+| Macro                                                  | Use it to                                                        | Guide                                                               |
+| ------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| [style()](style.md)                          | Style an element                                                 | [The basics of style()](../guides/style.md)                         |
+| [style.ref()](ref/index.md)                        | Style an element from another element's state, size, or position | [Element relationships](../guides/element-relationships.md)         |
+| [style.anchorScope()](anchor-scope.md)       | Limit where an anchor name is visible                            | [Element relationships](../guides/element-relationships.md)         |
+| [style.keyframes()](keyframes.md)            | Define an animation in a component                               | [Animations](../guides/animations.md)                               |
+| [style.viewTransition()](view-transition.md) | Style view transition snapshots and name each item               | [View transitions](../guides/view-transitions.md)                   |
+| [style.media()](media.md)                    | Use a named breakpoint as a media query in JavaScript            | [Responsive styles](../guides/responsive-styles.md)                 |
+| [style.css()](css.md)                        | Compile utilities into a CSS string for a shadow root            | [Web Components](../guides/web-components.md)                       |
+| [style.cva()](cva.md)                        | Migrate components that use `cva`                                | [Migrating from Tailwind CSS](../guides/migrating-from-tailwind.md) |
+
+Import the macros from the entrypoint of your framework, such as
+`stillwind/react`. The examples on these pages use React.
+
+Each example shows the source, the compiled code, and the CSS that it adds to
+the stylesheet. In development, Stillwind also adds checks that report invalid
+values at runtime. The compiled code on these pages leaves them out.
+[How styles compile](../concepts/how-styles-compile.md) explains the generated code in
+general.

package/docs/macros/keyframes.md

@@ -0,0 +1,98 @@
+---
+title: "style.keyframes()"
+description: "Define keyframes in a component, and apply them with animation options in style()."
+---
+
+# style.keyframes()
+
+`style.keyframes(definition)` defines an animation. Calling the result inside
+`style()` applies the animation, and its argument sets the animation's options.
+The compiler generates a unique animation name.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const fade = style.keyframes({
+  from: "opacity-0",
+  to: "opacity-100",
+});
+export const props = style(fade("duration-300 ease-in-out"));
+```
+
+### Compiled code
+
+```ts
+const fade = undefined;
+export const props = {className:"sw_4y7y6"};
+```
+
+### Generated CSS
+
+
+```css
+@keyframes sw-kf-74r1m {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+.sw_4y7y6 {
+  animation-name: sw-kf-74r1m;
+  animation-duration: .3s;
+  animation-timing-function: var(--ease-in-out);
+}
+```
+
+## Define the frames
+
+Write `style.keyframes()` as the initial value of a variable, with an object
+literal as its argument:
+
+| Key                                   | Value                                                                        |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| `from`, `to`, or a percentage         | A utility string for that frame, without variants                            |
+| A variant, such as `"motion-reduce:"` | A complete definition that replaces the whole animation under that condition |
+| `label`                               | An optional string literal that appears in the generated name                |
+
+Under a variant, the definition replaces every frame. It does not inherit frames
+from the ordinary definition. Use media and `supports-*` variants here. Selector
+and container variants are not supported.
+
+The declaration can be at the top level of a module, in a function, or in a
+callback. Each `style.keyframes()` call in the source creates one name, and the
+name stays the same in every render and function call. You can export the
+definition and import it in other modules.
+
+## Apply the animation
+
+Call the definition inside `style()`, such as `fade("duration-300 ease-in-out")`.
+The argument is a string literal of animation options. Timing utilities set
+animation properties here: `duration-300` sets `animation-duration`, not
+`transition-duration`. A utility that is not an animation option, such as
+`p-4`, produces no CSS, and
+[invalid-animation-option](../lints/invalid-animation-option.md) reports it.
+
+Write the call directly in `style()`. Storing `fade("duration-300")` in a
+variable causes [SW10004](../errors/SW10004.md).
+
+To turn the animation on or off by condition, put the call under a variant, such
+as `{ "motion-safe:": fade("duration-300") }`.
+
+## Generated code
+
+When the compiler knows which animation a call uses, the call becomes plain
+class names, and the definition variable can become `undefined` in JavaScript.
+The compiler writes every `@keyframes` rule that the calls need, together with
+the theme values that the frames use.
+
+See [Animations](../guides/animations.md) for task-based examples, and
+[invalid-keyframes-variant](../lints/invalid-keyframes-variant.md) for
+unsupported variants.