stillwind 0.0.0 → 0.1.0-rc.0

package/docs/errors/SW03001.md

@@ -0,0 +1,71 @@
+---
+title: "SW03001: Generated identifier collision"
+description: "Two different styles would receive the same generated name."
+---
+
+# SW03001: Generated identifier collision
+
+This error occurs when two different styles, refs, or animations would receive
+the same generated name. The usual cause is a custom `naming` function that
+returns the same name for different requests. A very short `hashLength` can also
+cause it.
+
+## Reported
+
+**stillwind.config.ts**
+
+```ts
+import { defineConfig } from "stillwind/config";
+
+export default defineConfig({
+  projects: [
+    {
+      css: "./src/stillwind.css",
+      files: ["src/**/*.tsx"],
+      namingRevision: "1",
+      naming: {
+        utilityClass: () => "button",
+      },
+    },
+  ],
+});
+```
+
+```tsx
+style("p-4");
+style("p-8");
+```
+
+> SW03001: generated identifier collision: button
+
+## Fixed
+
+```ts title="stillwind.config.ts"
+import { defineConfig } from "stillwind/config";
+
+export default defineConfig({
+  projects: [
+    {
+      css: "./src/stillwind.css",
+      files: ["src/**/*.tsx"],
+      namingRevision: "2",
+      naming: {
+        utilityClass: (_context, hash) => `button_${hash.toString("hex")}`,
+      },
+    },
+  ],
+});
+```
+
+```tsx
+style("p-4");
+style("p-8");
+```
+
+## How to fix
+
+- Include the hash passed as the callback's second argument in the name, as in
+  the example. This keeps the `button` prefix while distinguishing requests.
+  Return `null` to use the default name for a request.
+- If you use the default names, raise `hashLength`.
+- Change `namingRevision` whenever you change a `naming` function.

package/docs/errors/SW03002.md

@@ -0,0 +1,79 @@
+---
+title: "SW03002: Identifier generator failed"
+description: "A custom naming function threw an error or returned an invalid name."
+---
+
+# SW03002: Identifier generator failed
+
+This error occurs when a custom `naming` function fails while it generates a
+name. The message shows which kind of name it was generating and the error from
+the function. The compiler does not invent a name in its place.
+
+## Reported
+
+**stillwind.config.ts**
+
+```ts
+import { defineConfig } from "stillwind/config";
+
+export default defineConfig({
+  projects: [
+    {
+      css: "./src/stillwind.css",
+      files: ["src/**/*.tsx"],
+      namingRevision: "1",
+      naming: {
+        utilityClass(context, hash) {
+          if (!context.module.endsWith("Button.tsx")) {
+            throw new Error("Only Button.tsx is supported");
+          }
+          return `button_${hash.toString("hex")}`;
+        },
+      },
+    },
+  ],
+});
+```
+
+```tsx
+style("p-4");
+```
+
+> SW03002: identifier generation failed for class: Error: Only Button.tsx is supported
+
+## Fixed
+
+```ts title="stillwind.config.ts"
+import { defineConfig } from "stillwind/config";
+
+export default defineConfig({
+  projects: [
+    {
+      css: "./src/stillwind.css",
+      files: ["src/**/*.tsx"],
+      namingRevision: "2",
+      naming: {
+        utilityClass(context, hash) {
+          if (!context.module.endsWith("Button.tsx")) {
+            return null;
+          }
+          return `button_${hash.toString("hex")}`;
+        },
+      },
+    },
+  ],
+});
+```
+
+```tsx
+style("p-4");
+```
+
+The custom name still applies to `Button.tsx`. Other modules use default names.
+
+## How to fix
+
+- Reproduce the request from the message, and fix the function so that it returns
+  a name or `null` to keep the default name.
+- Keep the function pure: the same request must always produce the same name.
+- Change `namingRevision` whenever you change the function.

package/docs/errors/SW03003.md

@@ -0,0 +1,36 @@
+---
+title: "SW03003: Theme variable collision"
+description: "A theme variable takes the name of a custom property that Stillwind uses internally after themePrefix applies."
+---
+
+# SW03003: Theme variable collision
+
+This error occurs when `themePrefix` gives a theme variable the same name as a
+custom property that Stillwind registers for its utilities. The two values would
+replace each other, so the utilities that use them would break.
+
+## Reported
+
+With `themePrefix: "--tw-"`, the token below becomes `--tw-blur`. The `blur`
+utility already uses that property for its own value.
+
+```css
+@theme {
+  --blur: 3px;
+}
+```
+
+## Fixed
+
+```css
+@theme {
+  --blur-card: 3px;
+}
+```
+
+## How to fix
+
+- Rename the token so that its output name is free, as in the example.
+- Or set `tailwindPrefix` to another value, so that the internal properties
+  move out of the theme prefix. Plugins that write `--tw-` directly can stop
+  working when the two prefixes differ, so test them.

package/docs/errors/SW10001.md

@@ -0,0 +1,34 @@
+---
+title: "SW10001: JavaScript parse error"
+description: "The JavaScript or TypeScript of a file has a syntax error."
+---
+
+# SW10001: JavaScript parse error
+
+This error occurs when the compiler cannot parse the JavaScript or TypeScript of
+a file. The message shows the location and the explanation from the parser.
+
+## Reported
+
+```tsx
+export const props = style("p-4";
+```
+
+> SW10001: JavaScript parse error
+> 
+> Expected `,` or `)` but found `;`
+
+## Fixed
+
+```tsx
+export const props = style("p-4");
+```
+
+## How to fix
+
+- Fix the syntax at the location in the message, as in the example.
+- If the file parses in your editor, check that the integration treats it as the
+  right language, such as TypeScript with JSX for a `.tsx` file.
+
+Errors in code that a Vue, Svelte, or Astro converter generated are reported as
+[SW31004](SW31004.md) instead.

package/docs/errors/SW10002.md

@@ -0,0 +1,36 @@
+---
+title: "SW10002: Invalid component syntax"
+description: "A Vue, Svelte, or Astro component has a syntax error."
+---
+
+# SW10002: Invalid component syntax
+
+This error occurs when the parser of the framework cannot read a Vue, Svelte, or
+Astro component. The message shows the location and the explanation from that
+parser.
+
+## Reported
+
+```html
+<template><button></template>
+```
+
+> SW10002: invalid component syntax: SyntaxError: Element is missing end tag.
+> 
+> Source format: Vue
+> 
+> Converter: @vue/language-core@3.3.13
+
+## Fixed
+
+```html
+<template><button></button></template>
+```
+
+## How to fix
+
+Fix the syntax at the location in the message, as in the example, where the
+`<button>` element was not closed.
+
+If the component is valid but its converted script is not, the error is
+[SW31004](SW31004.md) instead.

package/docs/errors/SW10003.md

@@ -0,0 +1,30 @@
+---
+title: "SW10003: Invalid Unicode string"
+description: "A string used to generate CSS or resolve a module contains a lone Unicode surrogate."
+---
+
+# SW10003: Invalid Unicode string
+
+This error occurs when a static string contains an unpaired UTF-16 surrogate.
+Stillwind requires well-formed Unicode in strings that it compiles, including
+utility strings, declaration labels, and module specifiers.
+
+## Reported
+
+```tsx
+export const props = style("content-['\uD800']");
+```
+
+> SW10003: string contains invalid Unicode
+
+## Fixed
+
+```tsx
+export const props = style("content-['\u{1F600}']");
+```
+
+## How to fix
+
+Complete the surrogate pair, use a valid code point with `\u{...}`, or remove the
+invalid escape. Strings that Stillwind leaves for runtime evaluation can still
+contain lone surrogates.

package/docs/errors/SW10004.md

@@ -0,0 +1,39 @@
+---
+title: "SW10004: Unconsumed macro use"
+description: "A ref method, ref condition, or animation call is stored or passed somewhere other than directly in style()."
+---
+
+# SW10004: Unconsumed macro use
+
+Some calls have no value of their own. The compiler turns them into CSS at the
+place where `style()` uses them. This error occurs when such a call is stored in
+a variable or passed to another function instead.
+
+## Reported
+
+```tsx
+const card = style.ref("card");
+const container = card.asContainer("inline-size");
+```
+
+> SW10004: asContainer(...) must be consumed at its supported input position within style(); it cannot be materialized independently
+
+## Fixed
+
+```tsx
+const card = style.ref("card");
+const props = style(card, card.asContainer("inline-size"));
+```
+
+## How to fix
+
+Write the call directly where `style()` uses it:
+
+| Call                                                                                    | Where to write it                     |
+| --------------------------------------------------------------------------------------- | ------------------------------------- |
+| `card.asContainer()`, `card.asAnchor()`, `card.positionAnchor()`, `style.anchorScope()` | An argument of `style()`              |
+| An animation such as `fade("duration-300")`, and `transition.for(key)`                  | An argument of `style()`              |
+| `card()`, `card("hover")`, `.in()`, and `card.at()`                                     | A computed key, or a utility template |
+
+You can still store and pass the definitions themselves, such as the result of
+`style.ref()` or `style.keyframes()`, and the result of `style()`.

package/docs/errors/SW10005.md

@@ -0,0 +1,35 @@
+---
+title: "SW10005: Untransformed macro reference"
+description: "The style function is used as a value instead of being called."
+---
+
+# SW10005: Untransformed macro reference
+
+This error occurs when the code uses `style` or another macro as a value, such as
+by storing it in a variable or passing it to a function. The compiler replaces
+macro calls at build time and removes the import, so the function does not exist
+at runtime.
+
+## Reported
+
+```tsx
+import { style } from "stillwind/react";
+
+const macro = style;
+macro("p-4");
+```
+
+> SW10005: macro binding `style` has a reference that was not transformed at Span { file: FileId(2147483680), start: BytePos(56), end: BytePos(61) }
+
+## Fixed
+
+```tsx
+import { style as macro } from "stillwind/react";
+
+const props = macro("p-4");
+```
+
+## How to fix
+
+- Call `style()` directly, as in the example.
+- To share a style, store and pass the result of `style()`, not the function.

package/docs/errors/SW11001.md

@@ -0,0 +1,37 @@
+---
+title: "SW11001: Style composition cycle"
+description: "Two styles use each other as a base."
+---
+
+# SW11001: Style composition cycle
+
+This error occurs when styles use each other as a base, directly or through other
+styles. The CSS of a base comes before the CSS of the styles built on it, so a
+cycle has no valid order.
+
+## Reported
+
+```tsx
+const first = style(second, "rounded-md");
+const second = style(first, "p-4");
+```
+
+> SW11001: style composition dependency cycle
+
+## Fixed
+
+```tsx
+const base = style("rounded-md p-4");
+const first = style(base);
+const second = style(base);
+```
+
+## How to fix
+
+- If both styles need the same utilities, move those utilities into a third
+  base, as in the example.
+- If only one style extends the other, keep that dependency and remove the one
+  in the opposite direction.
+
+A cycle between whole modules is reported as [SW11002](SW11002.md)
+instead.

package/docs/errors/SW11002.md

@@ -0,0 +1,65 @@
+---
+title: "SW11002: CSS module ordering cycle"
+description: "Two modules each build styles on a base from the other module."
+---
+
+# SW11002: CSS module ordering cycle
+
+This error occurs when two modules each build a style on a base from the other
+module. The CSS of each module must come after the CSS of the modules that it
+builds on, so the two modules have no valid order, even when the individual
+styles do not form a cycle.
+
+## Reported
+
+**entry.ts**
+
+```ts
+import { style } from "stillwind/react";
+import { middle } from "./middle";
+
+export const base = style("p-4");
+export const derived = style(middle, "rounded-md");
+```
+
+**middle.ts**
+
+```ts
+import { style } from "stillwind/react";
+import { base } from "./entry";
+
+export const middle = style(base, "text-blue-600");
+```
+
+> SW11002: style composition requires cyclic CSS module ordering
+
+## Fixed
+
+```ts title="base.ts"
+import { style } from "stillwind/react";
+
+export const base = style("p-4");
+```
+
+```ts title="entry.ts"
+import { style } from "stillwind/react";
+import { middle } from "./middle";
+
+export { base } from "./base";
+export const derived = style(middle, "rounded-md");
+```
+
+```ts title="middle.ts"
+import { style } from "stillwind/react";
+import { base } from "./base";
+
+export const middle = style(base, "text-blue-600");
+```
+
+## How to fix
+
+- Move the shared bases into a module that both modules import, as in the
+  example.
+- Or put the styles that depend on each other in the same module.
+
+Changing the order of the imports does not fix it.

package/docs/errors/SW11003.md

@@ -0,0 +1,20 @@
+---
+title: "SW11003: Unavailable style base"
+description: "The compiled CSS of a base style is missing from the build."
+---
+
+# SW11003: Unavailable style base
+
+This error occurs when a style uses a base whose compiled CSS is not part of the
+build. The compiler must place the CSS of the base before the style, so it cannot
+continue without it.
+
+## How to fix
+
+- Import the base from its source module with a path that the bundler can
+  resolve.
+- If you write your own integration, keep the compiled results of all modules of
+  the same build together.
+
+A base whose type does not show its source is reported by
+[unverified-style-base](../lints/unverified-style-base.md).

package/docs/errors/SW12001.md

@@ -0,0 +1,43 @@
+---
+title: "SW12001: Incompatible declaration assignment"
+description: "A variable that holds one ref or animation is assigned a different one."
+---
+
+# SW12001: Incompatible declaration assignment
+
+This error occurs when a variable that holds one ref, keyframes, or view
+transition definition is later assigned a different one. The compiler tracks
+which definitions a variable can hold, and the assignment breaks that record.
+The message includes the explanation from TypeScript.
+
+## Reported
+
+```ts
+let current = style.ref("card");
+current = style.ref("panel");
+style({ [current("hover")]: "underline" });
+```
+
+> SW12001: incompatible declaration identities: TS2322: Type 'StyleRef<string>' is not assignable to type 'StyleRef<"stillwind-identity/v1:eyJraW5kIjoicmVmIiwibW9kdWxlSWQiOiJSZWZlcmVuY2UudHN4Iiwic3RhcnQiOjQ2LCJlbmQiOjUzLCJiaW5kaW5nTmFtZSI6ImN1cnJlbnQifQ">'.
+> Type 'string' is not assignable to type '"stillwind-identity/v1:eyJraW5kIjoicmVmIiwibW9kdWxlSWQiOiJSZWZlcmVuY2UudHN4Iiwic3RhcnQiOjQ2LCJlbmQiOjUzLCJiaW5kaW5nTmFtZSI6ImN1cnJlbnQifQ"'. Preserve declaration candidates with an explicit union or a generic parameter.
+> 
+> Source format: Jsx
+
+## Fixed
+
+```ts
+const card = style.ref("card");
+const panel = style.ref("panel");
+let current: typeof card | typeof panel = card;
+current = panel;
+style({ [current("hover")]: "underline" });
+```
+
+## How to fix
+
+- Declare each definition in its own `const`, and give the variable an explicit
+  union of their types, as in the example.
+- In a function that accepts several definitions, use a generic parameter instead
+  of a wider type.
+- Keep the types that TypeScript infers when you pass definitions through
+  exports.

package/docs/errors/SW12002.md

@@ -0,0 +1,42 @@
+---
+title: "SW12002: Declaration identities unavailable"
+description: "The compiler cannot tell which refs or animations a value can hold."
+---
+
+# SW12002: Declaration identities unavailable
+
+This error occurs when the compiler cannot tell which refs, keyframes, or view
+transitions a value can hold. When a ref is chosen at runtime, the compiler must
+generate CSS for every ref that it can be. A type annotation that widens the type
+hides that list.
+
+## Reported
+
+```ts
+const card = style.ref("card");
+const current: ReturnType<typeof style.ref> = card;
+style({ [current("hover")]: "underline" });
+```
+
+> SW12002: cannot determine finite declaration identities: Cannot determine a finite set of declaration identities. Preserve the value's inferred type, use an explicit union, or use a generic parameter.
+> 
+> Source format: Jsx
+
+## Fixed
+
+```ts
+const card = style.ref("card");
+const current = card;
+style({ [current("hover")]: "underline" });
+```
+
+## How to fix
+
+- Remove the type annotation, and keep the type that TypeScript infers, as in the
+  example.
+- When a value can hold several refs, use an explicit union of their types, such
+  as `typeof card | typeof panel`, or a generic parameter.
+- Make the source modules of the definitions reachable through imports.
+
+If the integration did not provide type information at all, the error is
+[SW30001](SW30001.md) instead.

package/docs/errors/SW13001.md

@@ -0,0 +1,35 @@
+---
+title: "SW13001: Authored CSS parse error"
+description: "Your stylesheet has a CSS syntax error."
+---
+
+# SW13001: Authored CSS parse error
+
+This error occurs when the compiler cannot parse a CSS rule in your stylesheet.
+The message explains what the parser expected.
+
+## Reported
+
+```css
+.card {
+  color blue;
+}
+```
+
+> SW13001: CSS parse error: Unexpected token Ident("blue") at :2:8
+
+## Fixed
+
+```css
+.card {
+  color: blue;
+}
+```
+
+## How to fix
+
+Fix the syntax that the message points to. In the example, the declaration needs
+a colon after `color`.
+
+A syntax error that the compiler finds while it collects custom properties is
+reported as [SW14006](SW14006.md) instead.

package/docs/errors/SW13002.md

@@ -0,0 +1,33 @@
+---
+title: "SW13002: Unterminated CSS block"
+description: "A CSS block in your stylesheet is not closed."
+---
+
+# SW13002: Unterminated CSS block
+
+This error occurs when a block in your stylesheet opens but does not close before
+the end of the file. The message gives the position as a byte offset from the
+start of the parsed text, counting from zero.
+
+## Reported
+
+```css
+.card {
+  color: blue;
+```
+
+> SW13002: unterminated CSS block at byte 27
+
+## Fixed
+
+```css
+.card {
+  color: blue;
+}
+```
+
+## How to fix
+
+- Add the missing `}`, `)`, or `]`.
+- Also check for an unclosed string or comment before that position. An unclosed
+  string can make the rest of the file look like one block.

package/docs/errors/SW13003.md

@@ -0,0 +1,18 @@
+---
+title: "SW13003: Invalid CSS block"
+description: "The compiler cannot read a balanced CSS block."
+---
+
+# SW13003: Invalid CSS block
+
+This error occurs when the compiler cannot consume a CSS block while it reads
+the stylesheet, imports, or plugin options. The message gives the position as a
+byte offset.
+
+## How to fix
+
+Check the delimiters around that position and any strings or comments inside the
+block. If the stylesheet is valid, report the source and the Stillwind version.
+
+An unclosed block normally produces [SW13002](SW13002.md). Other CSS
+syntax errors can produce [SW13001](SW13001.md).