stillwind 0.0.0 → 0.1.0-rc.0

package/docs/errors/SW13004.md

@@ -0,0 +1,45 @@
+---
+title: "SW13004: CSS nesting limit exceeded"
+description: "CSS rules or functions in your stylesheet are nested too deeply."
+---
+
+# SW13004: CSS nesting limit exceeded
+
+This error occurs when blocks or functions in your stylesheet are nested deeper
+than the compiler supports. The message gives the limit and the position where
+the nesting exceeds it.
+
+## Flatten selectors
+
+Replace nested selectors with their full selector. For example:
+
+```css
+.card {
+  & .content {
+    & .title {
+      color: blue;
+    }
+  }
+}
+```
+
+The same rule needs no nested blocks:
+
+```css
+.card .content .title {
+  color: blue;
+}
+```
+
+This small example is within the limit. Apply the same transformation to the
+deeply nested construct that the error identifies.
+
+## How to fix
+
+- Flatten nested rules, for example by writing the full selector instead of
+  nesting it.
+- Split a deeply nested value, such as many `calc()` calls inside each other,
+  into custom properties.
+
+Splitting the stylesheet into files does not help, because the limit applies to
+one construct.

package/docs/errors/SW14001.md

@@ -0,0 +1,44 @@
+---
+title: "SW14001: Missing utilities slot"
+description: "Your stylesheet does not place the generated utility CSS anywhere."
+---
+
+# SW14001: Missing utilities slot
+
+This error occurs when your stylesheet has no `@stillwind-slot utilities;`. The
+slot marks where the compiler writes the CSS of the utilities that you use. The
+default stylesheet contains it, so the error usually appears when a stylesheet
+imports only some parts of Stillwind.
+
+## Reported
+
+```css
+@import "stillwind/theme.css" layer(theme);
+@import "stillwind/builtins.css";
+```
+
+```tsx
+style("p-4");
+```
+
+> SW14001: generated utilities require an @stillwind-slot utilities; in the CSS entry graph
+
+## Fixed
+
+```css
+@import "stillwind/theme.css" layer(theme);
+@import "stillwind/utilities.css" layer(utilities);
+@import "stillwind/builtins.css";
+```
+
+```tsx
+style("p-4");
+```
+
+## How to fix
+
+- Import `stillwind/utilities.css`, which contains the slot, as in the example.
+- Or write `@stillwind-slot utilities;` where the utilities should go.
+- If you do not need a custom selection, import `stillwind` instead.
+
+Other slots that a feature needs are reported as [SW14002](SW14002.md).

package/docs/errors/SW14002.md

@@ -0,0 +1,47 @@
+---
+title: "SW14002: Missing support slot"
+description: "Your stylesheet has no place for CSS that a feature needs, such as keyframes."
+---
+
+# SW14002: Missing support slot
+
+This error occurs when the compiler generates supporting CSS, such as the
+`@keyframes` of an animation, but your stylesheet has no slot for it. The message
+names the missing slot.
+
+## Reported
+
+```css
+@import "stillwind/utilities.css" layer(utilities);
+@import "stillwind/builtins.css";
+```
+
+```tsx
+const fade = style.keyframes({
+  to: "opacity-0",
+});
+style(fade(""));
+```
+
+> SW14002: generated support requires an @stillwind-slot keyframes; in the CSS entry graph
+
+## Fixed
+
+```css
+@import "stillwind/utilities.css" layer(utilities);
+@import "stillwind/builtins.css";
+@stillwind-slot keyframes;
+```
+
+```tsx
+const fade = style.keyframes({
+  to: "opacity-0",
+});
+style(fade(""));
+```
+
+## How to fix
+
+- Add the slot that the message names, as in the example. `stillwind/theme.css`
+  contains the `theme` and `keyframes` slots.
+- If you do not need a custom selection, import `stillwind` instead.

package/docs/errors/SW14003.md

@@ -0,0 +1,38 @@
+---
+title: "SW14003: Malformed property requirement"
+description: "An @stillwind-require-properties directive in your stylesheet has invalid syntax."
+---
+
+# SW14003: Malformed property requirement
+
+This error occurs when an `@stillwind-require-properties` directive in your
+stylesheet has invalid syntax, such as an incomplete custom property name. The
+directive lists the registered custom properties that a utility needs.
+
+## Reported
+
+```css
+.card {
+  @stillwind-require-properties tw-rotate-x;
+  transform: var(--tw-rotate-x);
+}
+```
+
+> SW14003: invalid Stillwind property requirement at byte 9660
+
+## Fixed
+
+```css
+.card {
+  @stillwind-require-properties --tw-rotate-x;
+  transform: var(--tw-rotate-x);
+}
+```
+
+## How to fix
+
+Write each name in full, including the leading `--`, as in the example.
+
+A valid name that no registration provides is reported as
+[SW14005](SW14005.md). An invalid directive inside a utility from a
+plugin is reported as [SW14004](SW14004.md).

package/docs/errors/SW14004.md

@@ -0,0 +1,48 @@
+---
+title: "SW14004: Malformed utility property requirement"
+description: "A utility that you use has an @stillwind-require-properties directive with invalid syntax."
+---
+
+# SW14004: Malformed utility property requirement
+
+This error occurs when you use a utility whose definition contains an invalid
+`@stillwind-require-properties` directive. The message names the utility and the
+position in its definition. The definition can be in your stylesheet or in a
+plugin.
+
+## Reported
+
+```css
+@utility spin-x {
+  @stillwind-require-properties tw-rotate-x;
+  transform: var(--tw-rotate-x);
+}
+```
+
+```tsx
+style("spin-x");
+```
+
+> SW14004: utility `spin-x` has an invalid property requirement at body byte 0
+
+## Fixed
+
+```css
+@utility spin-x {
+  @stillwind-require-properties --tw-rotate-x;
+  transform: var(--tw-rotate-x);
+}
+```
+
+```tsx
+style("spin-x");
+```
+
+## How to fix
+
+- Write the full custom property name, including the leading `--`. In the
+  example, change `tw-rotate-x` to `--tw-rotate-x`.
+- If the definition comes from a plugin, report the utility and the plugin
+  version to the plugin's maintainer. Turning off a lint rule does not help.
+
+[SW14003](SW14003.md) covers the same mistake in an ordinary CSS rule.

package/docs/errors/SW14005.md

@@ -0,0 +1,51 @@
+---
+title: "SW14005: Required property is unregistered"
+description: "A utility requires a custom property that no @stillwind-property registers."
+---
+
+# SW14005: Required property is unregistered
+
+This error occurs when a utility requires a custom property, but no
+`@stillwind-property` in the loaded stylesheets registers it. The registration
+provides the initial value and other support CSS. Assigning the property in a
+rule does not register it.
+
+## Reported
+
+```css
+@utility spin-x {
+  @stillwind-require-properties --spin-angle;
+  rotate: var(--spin-angle);
+}
+```
+
+```tsx
+style("spin-x");
+```
+
+> SW14005: required custom property `--spin-angle` has no `@stillwind-property` registration
+
+## Fixed
+
+```css
+@stillwind-property --spin-angle {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@utility spin-x {
+  @stillwind-require-properties --spin-angle;
+  rotate: var(--spin-angle);
+}
+```
+
+```tsx
+style("spin-x");
+```
+
+## How to fix
+
+- Register the property with `@stillwind-property`, as in the example.
+- If the property comes from Stillwind or a plugin, check that the stylesheet
+  imports the file that registers it, and check the spelling of the name.

package/docs/errors/SW14006.md

@@ -0,0 +1,19 @@
+---
+title: "SW14006: Property-usage parse failure"
+description: "The compiler cannot parse CSS while collecting custom-property usage."
+---
+
+# SW14006: Property-usage parse failure
+
+This error occurs when the compiler cannot parse the CSS that it scans for
+custom-property usage. It needs that usage to select property registrations and
+initial values for the output stylesheet.
+
+## How to fix
+
+Correct the malformed CSS in the stylesheet or utility definition that produced
+it. If the authored CSS is valid, report a small reproduction and the Stillwind
+and plugin versions.
+
+Syntax errors found while the stylesheet loads usually produce
+[SW13001](SW13001.md) or [SW13002](SW13002.md) instead.

package/docs/errors/SW14007.md

@@ -0,0 +1,35 @@
+---
+title: "SW14007: Malformed theme reference"
+description: "A --theme() call in your stylesheet has invalid syntax."
+---
+
+# SW14007: Malformed theme reference
+
+This error occurs when a `--theme()` call in your stylesheet has invalid syntax,
+such as no token name.
+
+## Reported
+
+```css
+.card {
+  color: --theme();
+}
+```
+
+> SW14007: invalid --theme() reference at value byte 9667: invalid --theme() property `` at byte 0
+
+## Fixed
+
+```css
+.card {
+  color: --theme(--color-blue-500);
+}
+```
+
+## How to fix
+
+Write the full name of a theme token, with an optional fallback after a comma,
+such as `--theme(--color-brand, blue)`.
+
+A valid reference to a token that the theme does not define is reported by
+[invalid-theme-reference](../lints/invalid-theme-reference.md) instead.

package/docs/errors/SW14008.md

@@ -0,0 +1,41 @@
+---
+title: "SW14008: Circular utility application"
+description: "A utility applies itself directly or through another utility."
+---
+
+# SW14008: Circular utility application
+
+This error occurs when an `@apply` dependency returns to a utility that is already
+being expanded. The cycle can pass through several utilities.
+
+## Reported
+
+```css
+@utility card {
+  @apply card;
+}
+
+.card {
+  @apply card;
+}
+```
+
+> SW14008: circular @apply dependency for utility `card`
+
+## Fixed
+
+```css
+@utility card {
+  display: block;
+  padding: 1rem;
+}
+
+.card {
+  @apply card;
+}
+```
+
+## How to fix
+
+Remove the `@apply` that closes the dependency cycle. A shared utility can contain
+the common declarations, provided that it does not apply the utilities that use it.

package/docs/errors/SW15001.md

@@ -0,0 +1,18 @@
+---
+title: "SW15001: CSS offset exceeds source coordinates"
+description: "A stylesheet is too large for the compiler's source positions."
+---
+
+# SW15001: CSS offset exceeds source coordinates
+
+This error occurs when a stylesheet is so large that a position in it does not
+fit in the compiler's 32-bit source positions, which allow about 4 GB. Such a
+stylesheet is almost always generated by mistake.
+
+## How to fix
+
+- Find the tool or plugin that generates the stylesheet, and limit its output.
+- Split the stylesheet into several files.
+
+If the stylesheet has a normal size, report the error as a bug with the input
+sizes.

package/docs/errors/SW15002.md

@@ -0,0 +1,19 @@
+---
+title: "SW15002: Rendered source is too large"
+description: "A compiled module is too large for the compiler's source positions."
+---
+
+# SW15002: Rendered source is too large
+
+This error occurs when the compiled code of one module is so large that its
+positions do not fit in the compiler's 32-bit source positions. The source may be
+small while the compiled code is not, for example when a style lists a very large
+number of options.
+
+## How to fix
+
+- Split the module into smaller modules.
+- Reduce the number of style combinations that one call generates.
+
+If the module has a normal size, report the error as a bug with the size of the
+input and the output.

package/docs/errors/SW15003.md

@@ -0,0 +1,16 @@
+---
+title: "SW15003: Source size or offset is too large"
+description: "A source file or a position in it is too large for the compiler's source positions."
+---
+
+# SW15003: Source size or offset is too large
+
+This error occurs when a source file, or a position that the compiler is asked to
+read, does not fit in the compiler's 32-bit source positions. The message shows
+the value and the operation.
+
+## How to fix
+
+- Split a very large source file into smaller files.
+- If the file has a normal size, the position came from an integration or a tool.
+  Report the error with the operation from the message.

package/docs/errors/SW30001.md

@@ -0,0 +1,21 @@
+---
+title: "SW30001: TypeScript checker facts required"
+description: "The compiler needs type information for a value, but the integration did not provide it."
+---
+
+# SW30001: TypeScript checker facts required
+
+This error occurs when the compiler needs TypeScript type information to compile
+a value, but the integration compiled the file without it. Examples are a ref
+chosen by a condition, or an animation imported from another module. The message
+names the kind of value.
+
+## How to fix
+
+- With an official integration, update the Stillwind packages. If the error
+  remains, report it with the file that causes it.
+- In your own integration, run the type queries before compilation, and pass
+  their results with the same revision of the source.
+
+Type information that exists but does not match the source is reported as
+[SW30002](SW30002.md).

package/docs/errors/SW30002.md

@@ -0,0 +1,18 @@
+---
+title: "SW30002: Invalid or stale TypeScript facts"
+description: "The type information from the integration does not match the source or the compiler version."
+---
+
+# SW30002: Invalid or stale TypeScript facts
+
+This error occurs when the type information that the integration provides is
+invalid, or belongs to another revision of the source. For example, information
+from an older editor buffer does not apply to the edited text, even if the file
+path is the same.
+
+## How to fix
+
+- With an official integration, check that all `@stillwind/*` packages have the
+  same version, then update them. If the error remains, report it.
+- In your own integration, collect the type information again after every source
+  change, and use the host and native packages from the same release.

package/docs/errors/SW30003.md

@@ -0,0 +1,17 @@
+---
+title: "SW30003: Incompatible symbolic fact kinds"
+description: "The type information describes a value as the wrong kind, such as a keyframes definition as a ref."
+---
+
+# SW30003: Incompatible symbolic fact kinds
+
+This error occurs when the type information describes a value as a different kind
+of definition than the code uses it as. For example, it encodes a keyframes
+definition as a ref. The compiler cannot read the fields of one kind as another.
+
+## How to fix
+
+- With an official integration, update the Stillwind packages. If the error
+  remains, report it with the declaration and the code that uses it.
+- In your own integration, fix the conversion from TypeScript types to the
+  compiler's facts, and collect the facts again.

package/docs/errors/SW30004.md

@@ -0,0 +1,18 @@
+---
+title: "SW30004: Checker expression unavailable"
+description: "The integration cannot find the code that TypeScript needs to check for an expression."
+---
+
+# SW30004: Checker expression unavailable
+
+This error occurs when the compiler needs type information for an expression, but
+the integration cannot find that expression in the code that TypeScript checks.
+This usually happens in Vue, Svelte, or Astro components, where a converter
+produces the checked code. The message names the operation.
+
+## How to fix
+
+- With an official integration, update the Stillwind packages and the framework
+  packages. If the error remains, report it with the component.
+- In your own integration, keep the mapping between the original expressions and
+  the checked code, including for unsaved editor buffers.

package/docs/errors/SW31001.md

@@ -0,0 +1,20 @@
+---
+title: "SW31001: Invalid projection map"
+description: "The mapping between a component and its converted script is malformed."
+---
+
+# SW31001: Invalid projection map
+
+This error occurs when the map that links a Vue, Svelte, or Astro component to its
+converted script is malformed. For example, a range in the map extends past the
+end of the text that it refers to. The message describes the problem.
+
+## How to fix
+
+- With an official integration, update the Stillwind packages and the framework
+  packages. If the error remains, report it with the component.
+- In your own converter, check each range against the exact texts that you pass
+  to the compiler.
+
+A valid map that cannot point to one original range is reported as
+[SW31002](SW31002.md).

package/docs/errors/SW31002.md

@@ -0,0 +1,17 @@
+---
+title: "SW31002: Ambiguous or missing original range"
+description: "A Stillwind expression in a converted script maps to no place, or several places, in the component."
+---
+
+# SW31002: Ambiguous or missing original range
+
+This error occurs when a Stillwind expression in the converted script of a
+component maps to no place in the original component, or to more than one place.
+The compiler must edit the original source, so it needs exactly one location.
+
+## How to fix
+
+- With an official integration, update the Stillwind packages and the framework
+  packages. If the error remains, report it with the component.
+- In your own converter, map the whole expression. A mapping for a nearby token
+  is not enough.

package/docs/errors/SW31003.md

@@ -0,0 +1,18 @@
+---
+title: "SW31003: Projection content mismatch"
+description: "The converted script and the component contain different text at a mapped location."
+---
+
+# SW31003: Projection content mismatch
+
+This error occurs when the converted script and the original component contain
+different text at a location that the map links. The compiler would edit the
+wrong text, so it stops.
+
+## How to fix
+
+- With an official integration, save the file and build again, in case the
+  editor passed an old buffer. If the error remains, report it with the
+  component.
+- In your own converter, check rewrites and escaping of the mapped text, and do
+  not reuse a map for a changed buffer.

package/docs/errors/SW31004.md

@@ -0,0 +1,20 @@
+---
+title: "SW31004: Invalid converter output syntax"
+description: "The script that a converter generated from a valid component has a syntax error."
+---
+
+# SW31004: Invalid converter output syntax
+
+This error occurs when a Vue, Svelte, or Astro component is valid, but the script
+that the converter generates from it cannot be parsed. The message contains the
+explanation from the parser.
+
+## How to fix
+
+- With an official integration, update the Stillwind packages and the framework
+  packages. If the error remains, report it with the component.
+- In your own converter, fix the generated code, or select the right language
+  for the parser.
+
+A syntax error in the component itself is reported as
+[SW10002](SW10002.md) instead.

package/docs/errors/SW31005.md

@@ -0,0 +1,18 @@
+---
+title: "SW31005: Component projection preparation failed"
+description: "The converter for a Vue, Svelte, or Astro component failed before compilation."
+---
+
+# SW31005: Component projection preparation failed
+
+This error occurs when the converter that prepares a Vue, Svelte, or Astro
+component for compilation or type checking fails. The message contains the
+explanation from the converter.
+
+## How to fix
+
+- With an official integration, check that the framework and Stillwind package
+  versions are supported, and update them. If the error remains, report it with
+  the component.
+- In your own integration, report the converter failure instead of compiling a
+  partly prepared component.

package/docs/errors/SW31006.md

@@ -0,0 +1,17 @@
+---
+title: "SW31006: Invalid UTF-16 offset"
+description: "A requested UTF-16 offset is outside the source or inside a character."
+---
+
+# SW31006: Invalid UTF-16 offset
+
+This error occurs when an integration or a tool asks for a UTF-16 offset that is
+not a valid position in the source, such as an offset past the end. UTF-16
+offsets count code units, not bytes.
+
+## How to fix
+
+- With an official integration, report the error with the file and the action
+  that caused it.
+- In your own integration, use offsets from the same revision of the source, and
+  convert explicitly between byte offsets and UTF-16 offsets.

package/docs/errors/SW31007.md

@@ -0,0 +1,18 @@
+---
+title: "SW31007: Invalid UTF-16 position"
+description: "A requested line and column do not exist in the source."
+---
+
+# SW31007: Invalid UTF-16 position
+
+This error occurs when an integration or a tool asks for a line and column that
+do not exist in the source. Lines count from zero, and columns count UTF-16 code
+units from zero.
+
+## How to fix
+
+- With an official integration, report the error with the file and the action
+  that caused it.
+- In your own integration, convert positions from one-based editor numbers, and
+  compute them again after each edit. Do not use positions in the converted
+  script as positions in the original component.

package/docs/errors/SW31008.md

@@ -0,0 +1,16 @@
+---
+title: "SW31008: Invalid UTF-8 offset"
+description: "A requested byte offset is outside the source or inside a multibyte character."
+---
+
+# SW31008: Invalid UTF-8 offset
+
+This error occurs when an integration or a tool asks for a UTF-8 byte offset that
+is outside the source, or that falls inside a character of several bytes.
+
+## How to fix
+
+- With an official integration, report the error with the file and the action
+  that caused it.
+- In your own integration, use byte offsets for byte-based APIs. Convert UTF-16
+  editor positions with the source service instead of counting characters.