stillwind 0.0.0 → 0.1.0-rc.0

package/AGENTS_TEMPLATE.md

@@ -0,0 +1,5 @@
+## Stillwind
+
+- This project styles elements with [Stillwind](https://stillwind.dev/). Stillwind compiles Tailwind CSS v4 utilities in `style()` calls into element props and static CSS.
+- Before you change styles, read the relevant Markdown docs in `node_modules/stillwind/docs/`. Start with `guides/recommended-practices.md`. `node_modules/stillwind/skills/stillwind/SKILL.md` lists the page for each task.
+- After you change styles, run `stillwind lint --fix` and `stillwind fmt` through the project's package manager, and fix the remaining findings.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Stillwind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Stillwind
+
+Stillwind compiles Tailwind CSS v4 utilities into component props and static CSS.
+It uses theme rules and compiler checks to keep styling code in order, even when
+AI agents write much of it. See the [documentation](https://stillwind.dev/docs)
+and try it in the [Playground](https://play.stillwind.dev/).
+
+`stillwind` is the main Stillwind package. It provides CSS defaults, configuration
+helpers, and style APIs for Alpine, Astro, Lit, Preact, Qwik, React, Solid, Svelte,
+vanilla JavaScript, and Vue.
+
+## Install
+
+```sh
+vp i stillwind
+vp i -D @stillwind/integration
+```
+
+## Configure a project
+
+Create a CSS entrypoint:
+
+```css
+/* src/stillwind.css */
+@import "stillwind";
+
+@theme {
+  --color-accent: oklch(0.6 0.2 250);
+}
+```
+
+Select that stylesheet and your source files in `stillwind.config.ts`:
+
+```ts
+import { defineConfig } from "stillwind/config";
+
+export default defineConfig({
+  projects: [
+    {
+      css: "./src/stillwind.css",
+      files: ["src/**/*.{js,jsx,ts,tsx,vue,svelte,astro}"],
+    },
+  ],
+});
+```
+
+Register the [integration for your build tool](https://stillwind.dev/docs/integrations).
+For Vite, add `stillwind()` from `@stillwind/integration/vite` before the framework's
+JSX transform. The integration reads the project configuration and delivers its CSS.
+
+## Write styles
+
+Import `style` from the entrypoint for your framework:
+
+| Framework | Import              | Applying props               |
+| --------- | ------------------- | ---------------------------- |
+| Alpine    | `stillwind/alpine`  | `x-sw="props"`               |
+| Astro     | `stillwind/astro`   | `{...props}`                 |
+| Lit       | `stillwind/lit`     | `${applyStyle(props)}`       |
+| Preact    | `stillwind/preact`  | `{...props}`                 |
+| Qwik      | `stillwind/qwik`    | `{...props}`                 |
+| React     | `stillwind/react`   | `{...props}`                 |
+| Solid     | `stillwind/solid`   | `{...props}`                 |
+| Svelte    | `stillwind/svelte`  | `{...props}`                 |
+| Vanilla   | `stillwind/vanilla` | `applyStyle(element, props)` |
+| Vue       | `stillwind/vue`     | `v-bind="props"`             |
+
+Gatsby uses `stillwind/react`. Fresh 2 with Vite uses `stillwind/preact`.
+
+```tsx
+import { style } from "stillwind/react";
+
+const base = style("rounded-md bg-accent px-4 py-2 text-white");
+
+<button {...style(base, loading && "opacity-60")}>Save</button>;
+```
+
+Style arguments must be pure. The compiler does not guarantee their evaluation
+order or count, and it can omit unused evaluations. Perform effects outside style
+calls. Static styles emit CSS; dynamic values and conditions can require runtime helpers.
+Composed styles retain ordinary CSS specificity and importance.
+
+For vanilla JavaScript, import the macro and DOM helpers from `stillwind/vanilla`:
+
+```ts
+import { applyStyle, clearStyle, style } from "stillwind/vanilla";
+
+const button = document.querySelector("button")!;
+applyStyle(
+  button,
+  style("rounded-md px-4 py-2", {
+    "--accent": accent,
+  }),
+);
+clearStyle(button);
+```
+
+Call `applyStyle` again to replace the element's previous Stillwind contribution.
+The helper preserves existing classes and unrelated inline styles. `clearStyle`, or
+`applyStyle(element, {})`, removes the contribution and restores overwritten inline
+values and priorities. Inline values changed externally after the last application
+are preserved. HTML and SVG elements use the same helpers. The build integration
+delivers the generated CSS.
+
+For Alpine, register the plugin before starting Alpine. Write macro calls in JavaScript
+or TypeScript modules and pass their results to `x-sw`:
+
+```ts
+import Alpine from "alpinejs";
+import { stillwind, style } from "stillwind/alpine";
+
+Alpine.plugin(stillwind);
+Alpine.data("button", () => ({
+  active: false,
+  get props() {
+    return style("px-4 py-2", this.active && "bg-blue-500");
+  },
+}));
+Alpine.start();
+```
+
+```html
+<button x-data="button" x-sw="props" @click="active = !active">Toggle</button>
+```
+
+For Lit, pass the props to an element directive. Include the module's CSS in the
+component's shadow root:
+
+```ts
+import { html, LitElement, unsafeCSS } from "lit";
+import { applyStyle, style } from "stillwind/lit";
+import { css } from "stillwind/module-css";
+
+class SaveButton extends LitElement {
+  static styles = unsafeCSS(css);
+
+  render() {
+    return html`<button ${applyStyle(style("px-4 py-2"))}>Save</button>`;
+  }
+}
+```
+
+Lit's directive supports browser rendering. Lit SSR is unsupported. Use
+`stillwind({ automatic: false })` when styles belong only in shadow roots.
+Alpine and Lit updates replace the helper's previous contribution and preserve
+unrelated classes and inline styles. Removing the directive clears its contribution.
+Lit reapplies its latest props when the directive reconnects.
+
+Qwik uses ordinary JSX spreads. Keep Stillwind before the Qwik optimizer in the Vite
+plugin list. Compiled props contain plain class and style values that Qwik can serialize.
+
+## Customize and extend
+
+The default stylesheet imports the theme, preflight, utility slot, builtins, and
+templates. Custom CSS entries receive only the definitions they import. Individual
+stylesheets are available as `stillwind/theme.css`, `stillwind/preflight.css`,
+`stillwind/utilities.css`, `stillwind/builtins.css`, and `stillwind/templates.css`.
+
+Use `stillwind/config` for project settings and lint presets. `stillwind/css`
+provides helpers for explicit stylesheet placement, and `stillwind/module-css`
+exposes the compiled CSS of a producer module.
+
+- [Macro reference](https://stillwind.dev/docs/macros): refs, conditions, CVA, keyframes, and composition.
+- [Configuration](https://stillwind.dev/docs/configuration): scopes, lint rules, sorting, and namespaces.
+- [CSS ordering](https://stillwind.dev/docs/concepts/css-ordering): precedence when styles are composed.
+- [CSS delivery](https://github.com/SegaraRai/stillwind/blob/main/docs/css-emission.md): SSR, explicit CSS values, and Shadow DOM.

package/TAILWINDCSS-MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/css/builtin-metadata/sw-motion-properties.css

@@ -0,0 +1,186 @@
+/*
+Interpolable custom property registrations for the `keyframe` registry context.
+
+A keyframe interpolates a custom property only when its registration has a typed
+`syntax`. The Tailwind registrations use `syntax: "*"`, so a frame that sets
+`--tw-translate-y` switches its value halfway through the animation. The keyframe
+definitions in `sw-motion-contexts.css` write these properties instead.
+
+Each initial value is the identity of its transform or filter function, so a frame
+that sets one axis or one filter function keeps the others at their identity.
+Elements never set these properties; only keyframes do.
+`value-for` applies translation and filter length policies to their stored values.
+*/
+
+@stillwind-property --sw-motion-translate-x {
+  value-for: translate;
+  syntax: "<length-percentage>";
+  inherits: false;
+  initial-value: 0px;
+}
+
+@stillwind-property --sw-motion-translate-y {
+  value-for: translate;
+  syntax: "<length-percentage>";
+  inherits: false;
+  initial-value: 0px;
+}
+
+@stillwind-property --sw-motion-translate-z {
+  value-for: translate;
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+
+@stillwind-property --sw-motion-scale-x {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-scale-y {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-scale-z {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-rotate-x {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-rotate-y {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-rotate-z {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-skew-x {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-skew-y {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-blur {
+  value-for: filter;
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+
+@stillwind-property --sw-motion-brightness {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-contrast {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-grayscale {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+
+@stillwind-property --sw-motion-hue-rotate {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-invert {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+
+@stillwind-property --sw-motion-saturate {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-sepia {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+
+@stillwind-property --sw-motion-backdrop-blur {
+  value-for: backdrop-filter;
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+
+@stillwind-property --sw-motion-backdrop-brightness {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-backdrop-contrast {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-backdrop-grayscale {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+
+@stillwind-property --sw-motion-backdrop-hue-rotate {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+@stillwind-property --sw-motion-backdrop-invert {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+
+@stillwind-property --sw-motion-backdrop-opacity {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-backdrop-saturate {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 1;
+}
+
+@stillwind-property --sw-motion-backdrop-sepia {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}

package/css/builtin-metadata/tw-legacy-metadata.css

@@ -0,0 +1,36 @@
+/*
+Legacy Tailwind spellings that canonical lint rewrites to their current form.
+
+`@stillwind-legacy-utility old new;` renames a utility. A trailing `*` in both names
+keeps the rest of the name, so `start-*` to `inset-s-*` rewrites `start-4` to
+`inset-s-4`. The rewrite is used only when the old name does not resolve, or when both
+names produce the same CSS.
+
+`@stillwind-legacy-theme-key key --namespace-* [exposure];` names the theme namespace
+that a Tailwind v3 config key reads, as in Tailwind's compatibility layer. A config key
+without a statement reads the namespace with the kebab-case name of the key. The
+optional exposure decides how plugin configuration sees the CSS values of the namespace:
+`replace` replaces the v3 default values of the key, and `extend` adds the CSS values
+to them. Without an exposure, plugin configuration sees only the v3 default values.
+*/
+
+@stillwind-legacy-utility bg-gradient-to-* bg-linear-to-*;
+@stillwind-legacy-utility order-none order-0;
+@stillwind-legacy-utility overflow-ellipsis text-ellipsis;
+@stillwind-legacy-utility break-words wrap-break-word;
+@stillwind-legacy-utility start-* inset-s-*;
+@stillwind-legacy-utility end-* inset-e-*;
+
+@stillwind-legacy-theme-key animation --animate-* extend;
+@stillwind-legacy-theme-key aspectRatio --aspect-* extend;
+@stillwind-legacy-theme-key borderRadius --radius-* extend;
+@stillwind-legacy-theme-key boxShadow --shadow-* extend;
+@stillwind-legacy-theme-key colors --color-* replace;
+@stillwind-legacy-theme-key containers --container-*;
+@stillwind-legacy-theme-key fontFamily --font-*;
+@stillwind-legacy-theme-key fontSize --text-* extend;
+@stillwind-legacy-theme-key letterSpacing --tracking-* extend;
+@stillwind-legacy-theme-key lineHeight --leading-* extend;
+@stillwind-legacy-theme-key maxWidth --container-* extend;
+@stillwind-legacy-theme-key screens --breakpoint-* extend;
+@stillwind-legacy-theme-key transitionTimingFunction --ease-*;