stillwind 0.0.0 → 0.1.0-rc.0

package/docs/macros/media.md

@@ -0,0 +1,65 @@
+---
+title: "style.media()"
+description: "Turn named breakpoints and other media variants into a media query string for JavaScript."
+---
+
+# style.media()
+
+`style.media(...conditions)` returns a media query string, such as the argument
+of `matchMedia()`. It uses the definitions of variants such as `md:` and
+`motion-safe:` from your stylesheet, so JavaScript and CSS use the same
+conditions.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+export const query = style.media("md:motion-safe", "print");
+export const matches = window.matchMedia(query);
+```
+
+### Compiled code
+
+```ts
+export const query = "(width >= 48rem) and (prefers-reduced-motion: no-preference), print";
+export const matches = window.matchMedia(query);
+```
+
+### Generated CSS
+
+This macro adds no CSS to the stylesheet.
+
+This query matches a viewport at least as wide as `md` without a reduced-motion
+preference, or a printed page.
+
+## Inputs
+
+Each argument is a string literal or a template literal without interpolations.
+It contains one or more variants. The final colon is optional.
+
+| Form                     | Meaning                          |
+| ------------------------ | -------------------------------- |
+| Variants in one argument | Every condition must match       |
+| Several arguments        | At least one argument must match |
+
+Only variants that are media conditions are accepted. `hover` and other element
+states, `supports-*`, and container queries are not media conditions. An
+argument that is not a media condition is left out, and
+[invalid-media-query](../lints/invalid-media-query.md) reports it. When no
+argument remains, the result is `not all`.
+
+Write `style.media()` outside other Stillwind calls.
+
+## Output
+
+The compiler replaces the call with a string literal. The string has no `@media`
+and no braces. The call adds no CSS.
+
+When you change a breakpoint in your stylesheet, the string changes the next
+time the module compiles.
+
+`matchMedia()` is a browser API. Call it on the client, and remove its listeners
+when their component unmounts. See [Responsive styles](../guides/responsive-styles.md).

package/docs/macros/ref/as-anchor.md

@@ -0,0 +1,70 @@
+---
+title: "ref.asAnchor()"
+description: "Make the element that has a ref a named anchor for CSS anchor positioning."
+---
+
+# ref.asAnchor()
+
+`trigger.asAnchor(scope?)` sets `anchor-name` on the element. Position another
+element against it with [`trigger.positionAnchor()`](position-anchor.md).
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const trigger = style.ref("trigger");
+export const button = style(trigger, trigger.asAnchor());
+export const popover = style("absolute", trigger.positionAnchor(), "top-[anchor(bottom)]");
+```
+
+### Compiled code
+
+```ts
+const trigger = undefined;
+export const button = {className:"sw_l9spr sw_trigger_xnn7w"};
+export const popover = {className:"sw_mqosh"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_l9spr:where(.sw_trigger_xnn7w) {
+  anchor-name: --sw-a-trigger-xnn7w;
+}
+
+.sw_mqosh {
+  position-anchor: --sw-a-trigger-xnn7w;
+  position: absolute;
+  top: anchor(bottom);
+}
+```
+
+## Inputs
+
+The optional scope also sets `anchor-scope` on the element:
+
+| Scope            | Effect                                             |
+| ---------------- | -------------------------------------------------- |
+| Omitted          | Sets no `anchor-scope`                             |
+| `"all"`          | Limits every anchor name to this element's subtree |
+| `"none"`         | Sets `anchor-scope: none`                          |
+| An array of refs | Limits the anchor names of those refs              |
+
+Write the array directly in the call. The array includes the `trigger` ref only
+when you list it. An empty array sets nothing, and
+[ineffective-anchor-scope](../../lints/ineffective-anchor-scope.md) reports it.
+
+## Behavior
+
+Pass `trigger` and `trigger.asAnchor()` in the same `style()` call. The anchor
+name applies only to an element that has the ref, and
+[missing-ref-attachment](../../lints/missing-ref-attachment.md) reports a call
+without it.
+
+To limit the anchor name from an ancestor instead, use
+[style.anchorScope()](../anchor-scope.md). Stillwind generates CSS only,
+so check that the browsers you support implement anchor positioning.

package/docs/macros/ref/as-container.md

@@ -0,0 +1,64 @@
+---
+title: "ref.asContainer()"
+description: "Make the element that has a ref a named container for ref.at() queries."
+---
+
+# ref.asContainer()
+
+`card.asContainer(type?)` sets `container-name` on the element, and it sets
+`container-type` when you pass a type. Query the container with
+[`card.at()`](at.md).
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const card = style.ref("card");
+export const container = style(card, card.asContainer("inline-size"), "p-4");
+```
+
+### Compiled code
+
+```ts
+const card = undefined;
+export const container = {className:"sw_j0tj8 sw_card_uryy0"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_j0tj8 {
+  padding: calc(var(--spacing) * 4);
+}
+
+.sw_j0tj8:where(.sw_card_uryy0) {
+  container-name: sw-c-card-uryy0;
+  container-type: inline-size;
+}
+```
+
+## Inputs
+
+The type is a string literal:
+
+- `normal`, `size`, `inline-size`, or `scroll-state`
+- a supported combination of these
+- a CSS-wide keyword
+
+Without a type, Stillwind does not set `container-type`, and the cascade decides
+its value. A type stored in a variable is not accepted.
+
+## Behavior
+
+Pass `card` and `card.asContainer()` in the same `style()` call. The container
+declarations apply only to an element that has the ref, and
+[missing-ref-attachment](../../lints/missing-ref-attachment.md) reports a call
+without it.
+
+When another rule on the element also sets `container-name` or `container-type`,
+[conflicting-provider-properties](../../lints/conflicting-provider-properties.md)
+reports it.

package/docs/macros/ref/at.md

@@ -0,0 +1,68 @@
+---
+title: "ref.at()"
+description: "Style an element with a container query on the element that has a ref."
+---
+
+# ref.at()
+
+`card.at(query?)` creates a container query on the container that the `card` ref
+names. Make that element a container with
+[`card.asContainer()`](as-container.md).
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const card = style.ref("card");
+export const container = style(card, card.asContainer("inline-size"));
+export const child = style({ [card.at("width >= 40rem")]: "grid-cols-2" });
+```
+
+### Compiled code
+
+```ts
+const card = undefined;
+export const container = {className:"sw_28iqw sw_card_uryy0"};
+export const child = {className:"sw_cunr1"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_28iqw:where(.sw_card_uryy0) {
+  container-name: sw-c-card-uryy0;
+  container-type: inline-size;
+}
+
+@container sw-c-card-uryy0 (width >= 40rem) {
+  .sw_cunr1 {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+```
+
+## Inputs
+
+| Form                         | Generated condition                  |
+| ---------------------------- | ------------------------------------ |
+| `card.at("width >= 40rem")`  | `@container <name> (width >= 40rem)` |
+| ``card.at`width >= 40rem` `` | The same as the string form          |
+| `card.at()` or `card.at("")` | `@container <name>`                  |
+
+Write the query as a string literal or a tagged template without interpolations.
+Leave out the outer parentheses.
+
+## Behavior
+
+Without a query, the condition matches whenever the styled element is inside a
+container with the name.
+
+Write the call directly as a computed key in `style()`. You cannot store it in a
+variable and use it later.
+
+See [Element relationships](../../guides/element-relationships.md#react-to-a-containers-size)
+for a task-based example.

package/docs/macros/ref/condition.md

@@ -0,0 +1,86 @@
+---
+title: "ref() conditions"
+description: "Style an element while an ancestor with a ref exists or matches variants such as hover."
+---
+
+# ref() conditions
+
+Calling a ref creates a condition on the ref element. `card()` matches inside the
+element that has the `card` ref. `card("hover")` matches there while that element
+is hovered.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const card = style.ref("card");
+export const container = style(card, "rounded-lg p-4");
+export const title = style({ [card("hover")]: "text-blue-600" });
+```
+
+### Compiled code
+
+```ts
+const card = undefined;
+export const container = {className:"sw_vw9g3 sw_card_uryy0"};
+export const title = {className:"sw_c67by"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_vw9g3 {
+  padding: calc(var(--spacing) * 4);
+  border-radius: var(--radius-lg);
+}
+
+@media (hover: hover) {
+  .sw_c67by:is(:where(.sw_card_uryy0):hover *) {
+    color: var(--color-blue-600);
+  }
+}
+```
+
+## Inputs
+
+| Form                   | Matches                                               |
+| ---------------------- | ----------------------------------------------------- |
+| `card()`               | Inside the ref element                                |
+| `card("hover")`        | Inside the ref element while it matches the variant   |
+| `card("hover:active")` | Inside the ref element while it matches every variant |
+| ``card`hover` ``       | The same as `card("hover")`                           |
+
+The argument is a string literal or a tagged template without interpolations.
+The final colon is optional.
+
+## Where to write it
+
+Write the condition as a computed key of an object in `style()`:
+
+```ts
+style({ [card("hover")]: "text-blue-600" });
+```
+
+You can also write it as a variant segment inside a utility template, followed by
+`:`:
+
+```ts
+style(`${card("hover")}:text-blue-600`);
+```
+
+You cannot store the condition in a variable and use it later.
+
+## Behavior
+
+The ref element must be an ancestor of the styled element. To match a sibling or
+another element inside a shared ancestor, add [`.in()`](in.md).
+
+The condition only selects elements. It does not attach the ref, so attach it with
+`style(card)` on the ancestor.
+
+See [Element relationships](../../guides/element-relationships.md#react-to-a-parents-state)
+for a task-based example.

package/docs/macros/ref/in.md

@@ -0,0 +1,81 @@
+---
+title: "ref().in()"
+description: "Style an element from the state of a sibling, inside an ancestor that has another ref."
+---
+
+# ref().in()
+
+`trigger("hover").in(card)` matches while the `trigger` element is hovered and an
+element with the `card` ref contains both the `trigger` element and the styled
+element. Use it to style an element from the state of a sibling.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const card = style.ref("card");
+const trigger = style.ref("trigger");
+export const container = style(card, "p-4");
+export const button = style(trigger, "rounded-md px-4 py-2");
+export const text = style({ [trigger("hover").in(card)]: "text-blue-600" });
+```
+
+### Compiled code
+
+```ts
+const card = undefined;
+const trigger = undefined;
+export const container = {className:"sw_fxivy sw_card_uryy0"};
+export const button = {className:"sw_92u2q sw_trigger_fvqcy"};
+export const text = {className:"sw_yz349"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_fxivy {
+  padding: calc(var(--spacing) * 4);
+}
+
+.sw_92u2q {
+  padding-inline: calc(var(--spacing) * 4);
+  padding-block: calc(var(--spacing) * 2);
+  border-radius: var(--radius-md);
+}
+
+@media (hover: hover) {
+  .sw_yz349:is(:where(.sw_card_uryy0):has(:where(.sw_trigger_fvqcy):hover) *) {
+    color: var(--color-blue-600);
+  }
+}
+```
+
+## Inputs
+
+The receiver is a [ref condition](condition.md), such as
+`trigger("hover")` or `trigger()`. The argument is one of these:
+
+| Argument               | The scope element                           |
+| ---------------------- | ------------------------------------------- |
+| `card`                 | Has the `card` ref                          |
+| `card("focus-within")` | Has the `card` ref and matches the variants |
+
+The argument cannot use `.in()` or `.at()` itself.
+
+## Behavior
+
+The scope element must be a strict ancestor of both elements. It cannot be the
+styled element itself.
+
+Calling `.in()` more than once adds each scope as another condition, and every
+condition must match.
+
+Write the whole chain directly as a computed key in `style()`. You cannot store it
+in a variable and use it later.
+
+See [Element relationships](../../guides/element-relationships.md#react-to-a-siblings-state)
+for a task-based example.

package/docs/macros/ref/index.md

@@ -0,0 +1,115 @@
+---
+title: "style.ref() and ref methods"
+description: "Name an element with a ref, and style other elements from its state, size, or anchor position."
+---
+
+# style.ref() and ref methods
+
+`style.ref(label?)` creates a ref: a name for an element that other styles can
+refer to. Attach the ref to an element with `style(ref)`. Then use its methods to
+style other elements from that element's state, size, or position.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const card = style.ref("card");
+export const container = style(card, card.asContainer("inline-size"));
+export const child = style({
+  [card("hover")]: "text-blue-600",
+  [card.at("width >= 40rem")]: "grid-cols-2",
+});
+```
+
+### Compiled code
+
+```ts
+const card = undefined;
+export const container = {className:"sw_28iqw sw_card_uryy0"};
+export const child = {className:"sw_6hxbo"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_28iqw:where(.sw_card_uryy0) {
+  container-name: sw-c-card-uryy0;
+  container-type: inline-size;
+}
+
+@container sw-c-card-uryy0 (width >= 40rem) {
+  .sw_6hxbo {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (hover: hover) {
+  .sw_6hxbo:is(:where(.sw_card_uryy0):hover *) {
+    color: var(--color-blue-600);
+  }
+}
+```
+
+## Declare a ref
+
+Write `style.ref()` as the initial value of a variable: `const card = style.ref("card")`.
+The declaration can be at the top level of a module, in a function, or in a
+callback such as the one that you pass to `map()`.
+
+```tsx
+items.map((item) => {
+  const row = style.ref("row");
+  return (
+    <li {...style(row, "p-4")}>
+      <span {...style({ [row("hover")]: "underline" })}>{item}</span>
+    </li>
+  );
+});
+```
+
+The compiler generates a unique name for each `style.ref()` call in the source.
+The name stays the same in every render, loop iteration, and function call. You
+can export a ref, import it, and pass it as an argument.
+
+The argument of `style.ref()`, such as `"row"` in `style.ref("row")`, is a
+label. The label only makes the generated names easier to read, such as in the
+browser's developer tools. It does not make the name unique, and you can omit
+it: `const row = style.ref()`. Two refs with the same label stay separate, and
+so do two refs without a label. When you write a label, it must be a string
+literal.
+
+Because the name stays the same, a ref cannot distinguish nested elements that
+use the same declaration. For example, a tree node can render its child nodes
+inside its ref element. Every level then has the same name, and
+`node("hover")` matches while any ancestor node is hovered, not only the
+nearest one.
+
+## Methods
+
+| Method                                                     | Where to write it           | Effect                                                 |
+| ---------------------------------------------------------- | --------------------------- | ------------------------------------------------------ |
+| `ref`                                                      | A `style()` argument        | Attaches the ref to the element                        |
+| [`ref()`](condition.md)                      | A computed key in `style()` | Matches inside the ref element, optionally in a state  |
+| [`ref().in()`](in.md)                        | After a ref condition       | Matches inside a shared ancestor, such as for siblings |
+| [`ref.at()`](at.md)                          | A computed key in `style()` | Matches a container query on the ref element           |
+| [`ref.asContainer()`](as-container.md)       | A `style()` argument        | Makes the ref element a named container                |
+| [`ref.asAnchor()`](as-anchor.md)             | A `style()` argument        | Makes the ref element a named anchor                   |
+| [`ref.positionAnchor()`](position-anchor.md) | A `style()` argument        | Positions the styled element against the anchor        |
+
+Write each method call directly in `style()`. You cannot store the result of a
+method call in a variable and use it later.
+
+## Generated code
+
+When the compiler knows which ref a call uses, the ref becomes plain class names
+and selectors, and the ref variable can become `undefined` in JavaScript. When a
+call chooses among several refs at runtime, the generated code keeps the fields
+that the choice needs. The compiled code reads those fields directly. In
+development, Stillwind checks them first. The code does not watch the DOM.
+
+See [Element relationships](../../guides/element-relationships.md) for task-based
+examples.

package/docs/macros/ref/position-anchor.md

@@ -0,0 +1,64 @@
+---
+title: "ref.positionAnchor()"
+description: "Position the styled element against the anchor that a ref names."
+---
+
+# ref.positionAnchor()
+
+`trigger.positionAnchor()` sets `position-anchor` on the styled element, so that
+`anchor()` values in its other utilities refer to the `trigger` anchor.
+
+## Example
+
+### Source
+
+```tsx
+import { style } from "stillwind/react";
+
+const trigger = style.ref("trigger");
+export const button = style(trigger, trigger.asAnchor());
+export const popover = style(
+  "absolute",
+  trigger.positionAnchor(),
+  "top-[anchor(bottom)] left-[anchor(left)]",
+);
+```
+
+### Compiled code
+
+```ts
+const trigger = undefined;
+export const button = {className:"sw_l9spr sw_trigger_xnn7w"};
+export const popover = {className:"sw_fu7et"};
+```
+
+### Generated CSS
+
+
+```css
+.sw_l9spr:where(.sw_trigger_xnn7w) {
+  anchor-name: --sw-a-trigger-xnn7w;
+}
+
+.sw_fu7et {
+  position-anchor: --sw-a-trigger-xnn7w;
+  position: absolute;
+  top: anchor(bottom);
+  left: anchor(left);
+}
+```
+
+## Inputs
+
+`positionAnchor()` takes no arguments.
+
+## Behavior
+
+The styled element does not need the `trigger` ref. The anchor element needs it,
+together with [`trigger.asAnchor()`](as-anchor.md).
+
+Write the call directly in `style()`. You cannot store it in a variable and use
+it later.
+
+See [Element relationships](../../guides/element-relationships.md#position-an-element-at-an-anchor)
+for a complete example with an anchor scope.