@yak/solid 0.0.0

package/runtime/cssProp.ts

@@ -0,0 +1,26 @@
+/**
+ * Adds the yak `css` prop to Solid's JSX types.
+ *
+ * Solid compiles JSX natively (via babel-preset-solid), so unlike React
+ * there is no jsx-runtime module to wrap. Importing "@yak/solid" is enough
+ * to activate this augmentation.
+ *
+ * The css prop is compiled away by the yak SWC plugin into a
+ * `__yak_mergeCssProp` spread; on custom components it requires the
+ * component to accept `class` and `style` props.
+ */
+import type { ComponentStyles } from "./cssLiteral.ts";
+
+declare module "@solidjs/web" {
+  namespace JSX {
+    // ElementAttributes is the shared base of HTMLAttributes, SVGAttributes
+    // and MathMLAttributes in Solid 2. Declaration merging requires the type
+    // parameter to keep Solid's original name.
+    // eslint-disable-next-line no-unused-vars
+    interface ElementAttributes<T> {
+      css?: ComponentStyles<{}>;
+    }
+  }
+}
+
+export {};

package/runtime/globalStyle.ts

@@ -0,0 +1,54 @@
+import type { ComponentStyles } from "./cssLiteral.js";
+import type { YakComponent } from "./publicStyledApi.js";
+
+/**
+ * Values that may be interpolated into a `globalStyle` template.
+ *
+ * Only build-time values are allowed: constants, `keyframes` animation names,
+ * static `css` mixins and styled-component selectors. Runtime functions
+ * (`${(props) => ...}`) are intentionally excluded: a global rule has no element
+ * to attach a CSS variable to. Declare a CSS custom property instead and toggle
+ * it via an attribute/class on the root element.
+ */
+export type GlobalStyleInterpolation = string | number | ComponentStyles<{}> | YakComponent<any>;
+
+/**
+ * Declares global, unscoped styles that ride the same zero-runtime extraction
+ * pipeline as `styled` and `keyframes`.
+ *
+ * Global styles are **part of the stylesheet, not part of the render tree**.
+ * They apply exactly when the module declaring them is included in the bundle,
+ * typically by importing it from a layout or entry point. They cannot be
+ * conditionally mounted; express conditions in CSS (`@media`, `@supports`,
+ * `:root[data-theme]`, `:has()`) or through CSS custom properties.
+ *
+ * @usage
+ *
+ * ```tsx
+ * import { globalStyle, keyframes } from "@yak/solid";
+ *
+ * const fadeIn = keyframes`
+ *   from { opacity: 0; }
+ * `;
+ *
+ * globalStyle`
+ *   :root {
+ *     --spacing: 4px;
+ *   }
+ *
+ *   body {
+ *     margin: 0;
+ *   }
+ *
+ *   ::view-transition-new(root) {
+ *     animation: ${fadeIn} 200ms ease;
+ *   }
+ * `;
+ * ```
+ */
+export const globalStyle = (
+  _styles: TemplateStringsArray,
+  ..._values: Array<GlobalStyleInterpolation>
+): void => {
+  return undefined;
+};

package/runtime/index.ts

@@ -0,0 +1,39 @@
+/**
+ * This file contains the typings for the public API for @yak/solid and testing mocks
+ *
+ * IMPORTANT: In production builds, imports to this file should be replaced by the SWC plugin.
+ * If you're seeing this code in a production environment, your build process may not be configured correctly.
+ *
+ * Purpose:
+ * 1. Provide a test-friendly version of the @yak/solid API
+ * 2. Offer type definitions for the public API
+ *
+ * Usage in tests:
+ * - Import from "@yak/solid" as usual in your test files
+ * - These mock implementations will be used instead of the actual runtime
+ *
+ * Warning for production:
+ * - If these exports are used in a production build, styles will not be applied correctly
+ * - Ensure your build process is configured to use the yak-swc SWC plugin
+ *   (e.g. via `yak` from "@yak/solid/vite")
+ *
+ * For maintainers:
+ * - Keep this API surface in sync with the actual implementation in @yak/solid/internal
+ * - Ensure mock implementations here are suitable for testing purposes
+ */
+
+import "./cssProp.js";
+
+// the context is a package-level export so the vite plugin can alias
+// "@yak/solid/context/baseContext" to the user's theme context file
+export { useTheme, YakThemeProvider, YakThemeContext } from "@yak/solid/context";
+export type { YakTheme } from "./context/index.ts";
+
+export type { GenericYakComponentOf, YakComponent } from "./publicStyledApi.ts";
+
+export { atoms } from "./atoms.js";
+export { css } from "./mocks/cssLiteral.js";
+export { keyframes } from "./mocks/keyframes.js";
+export { styled } from "./mocks/styled.js";
+export { globalStyle } from "./mocks/globalStyle.js";
+export type { GlobalStyleInterpolation } from "./mocks/globalStyle.js";

package/runtime/internal.ts

@@ -0,0 +1,41 @@
+/**
+ * IMPORTANT: This file contains the internal implementation of @yak/solid's core APIs.
+ *
+ * Purpose:
+ * - Provides the actual runtime implementations for styled, css, keyframes, etc.
+ * - Referenced only by the compiled code "@yak/solid/internal"
+ *
+ * Usage:
+ * - DO NOT import from this file directly in your application code.
+ * - Always use `import { ... } from "@yak/solid"` in your source files.
+ * - The SWC plugin will automatically transform those imports to use this internal module.
+ *
+ * Why this exists:
+ * 1. Allows for cleaner separation between the public API and internal implementation
+ * 2. Enables better typing for both pre-compilation (user code) and post-compilation scenarios
+ * 3. Easier testing and snapshot comparisons without hashes (in index.ts)
+ * 4. Makes @yak/solid work out-of-the-box with testing frameworks like Jest and Vitest
+ *
+ * Note for maintainers:
+ * - Ensure that types from this file are not published to avoid exposing internal APIs.
+ *
+ * @internal This module is not intended for direct usage and may change without notice.
+ */
+
+export { css } from "./cssLiteral.js";
+export { styled } from "./styled.js";
+export { atoms } from "./atoms.js";
+export { keyframes } from "./keyframes.js";
+export { globalStyle } from "./globalStyle.js";
+
+// the context is a package-level export so the vite plugin can alias
+// "@yak/solid/context/baseContext" to the user's theme context file
+export { useTheme, YakThemeProvider, YakThemeContext } from "@yak/solid/context";
+
+// runtime internals (helpers which get injected by the compiler)
+export { unitPostFix as __yak_unitPostFix } from "./internals/unitPostFix.js";
+export { mergeCssProp as __yak_mergeCssProp } from "./internals/mergeCssProp.js";
+export { mergeClasses as __yak_mergeClassNames } from "./internals/mergeClasses.js";
+
+// export shorthand for DOM styled components (e.g. for styled.div)
+export * from "./styledDom.js";

package/runtime/internals/mergeClasses.ts

@@ -0,0 +1,36 @@
+/**
+ * Normalize Solid `class` values for string merging.
+ * Solid 2 allows strings, arrays and object syntax on the class attribute.
+ */
+export const normalizeClass = (value: unknown): string => {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map(normalizeClass).filter(Boolean).join(" ");
+  if (typeof value === "object") {
+    return Object.keys(value)
+      .filter((key) => (value as Record<string, unknown>)[key])
+      .join(" ");
+  }
+  return String(value);
+};
+
+/**
+ * Merges the folded yak class name with a user `class` value.
+ *
+ * Injected by the compiler (as `__yak_mergeClassNames`) when it replaces a JSX
+ * usage of a fully static styled component with a plain element:
+ * ```tsx
+ * const Card = styled.div`color: red;`;
+ * <Card class={active() && "active"} />
+ * ```
+ * becomes
+ * ```tsx
+ * <div class={__yak_mergeClassNames("yX", active() && "active")} />
+ * ```
+ */
+export const mergeClasses = (yakClass: string, userClass: unknown): string | undefined => {
+  const user = normalizeClass(userClass);
+  if (!yakClass) return user || undefined;
+  if (!user) return yakClass;
+  return yakClass + " " + user;
+};

package/runtime/internals/mergeCssProp.ts

@@ -0,0 +1,54 @@
+import { Classes } from "../cssLiteral.js";
+import { RuntimeStyleProcessor } from "../publicStyledApi.js";
+
+/**
+ * This is an internal helper function to merge relevant props of a native element with a css prop.
+ * It's automatically added when using the `css` prop in a JSX element.
+ * e.g.:
+ * ```tsx
+ * <p
+ *  class="foo"
+ *  css={css`
+ *   color: green;
+ * `}
+ * {...{ style: { padding: "30px" }}}
+ * />
+ */
+export const mergeCssProp = (
+  relevantProps: {
+    class?: string;
+    style?: Record<string, string>;
+  } & Record<string, unknown>,
+  cssProp: RuntimeStyleProcessor<unknown> | false | null | undefined,
+) => {
+  const classes = new Classes(relevantProps.class);
+
+  const existingStyle = relevantProps.style;
+  const style = existingStyle ? { ...existingStyle } : {};
+
+  // a falsy css prop applies no styles, e.g. `css={on && css`...`}` with `on` false
+  if (cssProp) {
+    cssProp({}, classes, style);
+  }
+
+  // Forward all other props (onClick, aria-*, id, …) untouched and only
+  // override class/style with the merged result — the transform already
+  // built `relevantProps` in JSX attribute order, so this preserves overrides.
+  const result: Record<string, unknown> & {
+    class?: string;
+    style?: Record<string, string>;
+  } = { ...relevantProps };
+
+  if (Object.keys(style).length > 0) {
+    result.style = style;
+  } else {
+    delete result.style;
+  }
+  if (classes.value) {
+    result.class = classes.value;
+  } else {
+    delete result.class;
+  }
+
+  return result;
+};

package/runtime/internals/unitPostFix.ts

@@ -0,0 +1,34 @@
+/**
+ * Internal helper called by transformed code. Do not use directly.
+ *
+ * Takes a function and a css unit and returns the result of the function concatenated with the unit
+ *
+ * ```tsx
+ * import { styled } from "@yak/solid";
+ *
+ * const Button = styled.button<{ $width?: boolean }>`
+ *   width: ${({ $width }) => $width}px;
+ * `;
+ * ```
+ *
+ * Which will be transformed to:
+ *  ```tsx
+ * import { styled } from "@yak/solid/internal";
+ *
+ * const Button = styled.button<{ $width?: boolean }>(
+ *  "button", {
+ *   width: unitPostFix({ $width }) => $width, "px")
+ * });
+ */
+export const unitPostFix = (arg: unknown, unit: string) => {
+  switch (typeof arg) {
+    case "function":
+      return (props: any) => unitPostFix(arg(props), unit);
+    case "number":
+    case "string":
+      return `${arg}${unit}`;
+    // Ignore falsy values
+    default:
+      return undefined;
+  }
+};

package/runtime/keyframes.ts

@@ -0,0 +1,30 @@
+/**
+ * Allows to use CSS keyframe animations in a styled or css block
+ *
+ * @usage
+ *
+ * ```tsx
+ * import { styled, keyframes } from "@yak/solid";
+ *
+ * const rotate = keyframes`
+ *  from {
+ *   transform: rotate(0deg);
+ *  }
+ *  to {
+ *   transform: rotate(360deg);
+ *  }
+ * `;
+ *
+ * const Spinner = styled.div`
+ *   animation: ${rotate} 1s linear infinite;
+ * `;
+ * ```
+ */
+export const keyframes = <T extends (string | number | bigint)[] = never>(
+  styles: TemplateStringsArray,
+  ..._dynamic: T
+): string => {
+  // during compilation all args of keyframe are compiled
+  // to a string which references the animation name
+  return styles as any as string;
+};

package/runtime/mocks/cssLiteral.ts

@@ -0,0 +1,74 @@
+import type { css as cssInternal, NestedRuntimeStyleProcessor } from "../cssLiteral.js";
+
+export type { ComponentStyles, CSSInterpolation } from "../cssLiteral.js";
+
+/**
+ * Allows to use CSS styles in a styled or css block
+ *
+ * e.g.
+ *
+ * ```tsx
+ * const Component = styled.div`
+ *  color: black;
+ *  ${({$active}) => $active && css`color: red;`}
+ * `;
+ * ```
+ */
+export const css: typeof cssInternal = (styles: TemplateStringsArray, ...args: unknown[]) => {
+  // When called in yak files as a template tag (without SWC transformation),
+  // return { __yak: rawCss } so the cross-file resolver can
+  // extract the mixin value from evaluated .yak files.
+  if (Array.isArray(styles) && "raw" in styles) {
+    let rawCss = styles[0];
+    for (let i = 0; i < args.length; i++) {
+      const interpolation = args[i];
+      rawCss +=
+        interpolation && typeof interpolation === "object" && "__yak" in interpolation
+          ? (interpolation as { __yak: string }).__yak
+          : String(interpolation);
+      rawCss += styles[i + 1];
+    }
+    return { __yak: rawCss } as any;
+  }
+
+  const dynamicCssFunctions: NestedRuntimeStyleProcessor[] = [];
+  for (const arg of args as Array<string | Function | object>) {
+    // Dynamic CSS e.g.
+    // css`${props => props.active && css`color: red;`}`
+    // compiled -> css((props: { active: boolean }) => props.active && css("yak31e4"))
+    if (typeof arg === "function") {
+      dynamicCssFunctions.push(arg as unknown as NestedRuntimeStyleProcessor);
+    }
+  }
+  if (dynamicCssFunctions.length === 0) {
+    return {
+      class: "",
+      style: undefined,
+    };
+  }
+  return ((props: unknown) => {
+    for (let i = 0; i < dynamicCssFunctions.length; i++) {
+      // run the dynamic expressions and ignore the return value
+      // the execution is important to ensure that the user code is executed
+      // the same way as in the real runtime
+      executeDynamicExpressionRecursively(props, dynamicCssFunctions[i]);
+    }
+    return {
+      class: "",
+      style: undefined,
+    };
+  }) as any;
+};
+
+function executeDynamicExpressionRecursively(
+  props: unknown,
+  expression: NestedRuntimeStyleProcessor,
+) {
+  const classes = new Set<string>();
+  const style = {};
+  let result = expression(props, classes, style);
+  while (typeof result === "function") {
+    result = result(props, classes, style);
+  }
+  return result;
+}

package/runtime/mocks/globalStyle.ts

@@ -0,0 +1,14 @@
+import type { globalStyle as globalStyleInternal } from "../globalStyle.js";
+
+export type { GlobalStyleInterpolation } from "../globalStyle.js";
+
+/**
+ * Test-friendly mock of `globalStyle`.
+ *
+ * `globalStyle` has no runtime behaviour: the SWC plugin extracts its CSS at
+ * build time and replaces the call with a no-op. The mock mirrors that: it does
+ * nothing so yak files can be imported in Jest/Vitest without the compiler.
+ */
+export const globalStyle: typeof globalStyleInternal = (_styles, ..._values) => {
+  // no-op in the mock
+};

package/runtime/mocks/keyframes.ts

@@ -0,0 +1,29 @@
+import type { keyframes as keyframesInternal } from "../keyframes.js";
+
+/**
+ * Allows to use CSS keyframe animations in a styled or css block
+ *
+ * @usage
+ *
+ * ```tsx
+ * import { styled, keyframes } from "@yak/solid";
+ *
+ * const rotate = keyframes`
+ *  from {
+ *   transform: rotate(0deg);
+ *  }
+ *  to {
+ *   transform: rotate(360deg);
+ *  }
+ * `;
+ *
+ * const Spinner = styled.div`
+ *   animation: ${rotate} 1s linear infinite;
+ * `;
+ * ```
+ */
+export const keyframes: typeof keyframesInternal = (_styles, ..._dynamic) => {
+  // the keyframes function is a no-op in the mock
+  // as it has no dynamic runtime behavior but only css
+  return "";
+};

package/runtime/mocks/styled.ts

@@ -0,0 +1,8 @@
+import type { JSX } from "@solidjs/web";
+import { styled as StyledFactory } from "../styled.js";
+
+export const styled = /* @__PURE__ */ new Proxy(StyledFactory, {
+  get(target, TagName: keyof JSX.IntrinsicElements) {
+    return target(TagName);
+  },
+}) as typeof StyledFactory;

package/runtime/publicStyledApi.ts

@@ -0,0 +1,177 @@
+// This is the public facing API for the styled object.
+import type { JSX } from "@solidjs/web";
+import type { YakTheme } from "./context/index.js";
+import type { Accessor } from "solid-js";
+import { CSSInterpolation, yakComponentSymbol } from "./cssLiteral.js";
+
+/**
+ * Component signature accepted and produced by `styled`.
+ *
+ * Intentionally NOT Solid 2's `Component` type: that alias constrains props
+ * to `Record<string, any>` which does not compose with the `object`-based
+ * generics of the styled API (kept in sync with the React runtime).
+ */
+export type AnyComponent<T> = (props: T) => JSX.Element;
+
+/**
+ * Style object the runtime writes CSS custom properties into.
+ * Solid also allows string styles on elements; the runtime normalizes
+ * those to objects before processing (see `unwrapStyle` in styled.ts).
+ */
+export type StyleObject = JSX.CSSProperties & Record<`--${string}`, string | number | undefined>;
+
+/**
+ * Main styled interface that combines HTML tag mappings with the styled function.
+ * This is the primary entry point for creating styled components.
+ */
+export interface Styled extends MappedHtmlTags, StyledFn {}
+
+/**
+ * Function interface for creating styled components from any component or HTML tag.
+ * Supports Solid components, HTML tags, and custom web components.
+ */
+export interface StyledFn {
+  <TProps extends object = JSX.ElementAttributes<Element>>(
+    Component: HtmlTags | AnyComponent<TProps> | CustomWebComponentTag,
+  ): LiteralWithAttrs<TProps>;
+}
+
+/**
+ * A yak component with a special symbol that allows component targeting
+ * and proper attrs function handling.
+ * @example styled.svg`${Button}:hover & { fill: red; }` or styled(Button)`color: red;`
+ */
+export interface YakComponent<T> extends AnyComponent<T> {
+  // This is intentionally typed to hide the internal implementation details.
+  [yakComponentSymbol]: [unknown, unknown, unknown, unknown];
+}
+
+/**
+ * Styled component with attrs method for adding default props.
+ * Extends StyledLiteral with the ability to specify default attributes.
+ */
+export interface LiteralWithAttrs<T extends object> extends StyledLiteral<T> {
+  attrs: <
+    TAttrsIn extends object = {},
+    TAttrsOut extends AttrsMerged<T, TAttrsIn> = AttrsMerged<T, TAttrsIn>,
+  >(
+    attrs: Attrs<T, TAttrsIn, TAttrsOut>,
+  ) => StyledLiteral<Substitute<T, TAttrsIn>>;
+}
+
+/**
+ * Template literal function for defining CSS styles with interpolation support.
+ * Accepts CSS template strings and interpolated values with proper typing.
+ */
+export interface StyledLiteral<T> {
+  <TCSSProps>(
+    styles: TemplateStringsArray,
+    ...values: Array<
+      CSSInterpolation<
+        T &
+          // Prevent TypeScript from inferring types from template literal usage
+          // This ensures proper typing and enables destructuring hints
+          NoInfer<TCSSProps> & { theme: Accessor<YakTheme> }
+      >
+    >
+  ): YakComponent<TCSSProps & T>;
+}
+
+/**
+ * Function variant of attrs that receives current props and returns additional props.
+ * Allows for dynamic prop generation based on component state.
+ */
+export interface AttrsFunction<
+  TBaseProps,
+  TIn extends object = {},
+  TOut extends AttrsMerged<TBaseProps, TIn> = AttrsMerged<TBaseProps, TIn>,
+> {
+  (p: Substitute<TBaseProps & { theme: Accessor<YakTheme> }, TIn>): Partial<TOut>;
+}
+
+/**
+ * Merges provided props with initial props, making specified props optional.
+ * Includes theme support for styled components.
+ */
+export type AttrsMerged<TBaseProps, TIn extends object = {}> = Substitute<
+  TBaseProps & { theme?: Accessor<YakTheme> },
+  TIn
+>;
+
+/**
+ * Maps all HTML tag names to their corresponding styled component types with attributes support.
+ * Provides typed access to all standard HTML elements through the styled interface.
+ */
+export type MappedHtmlTags = {
+  [Tag in HtmlTags]: LiteralWithAttrs<JSX.IntrinsicElements[Tag]>;
+};
+
+/**
+ * The attrs function allows adding additional props to a styled component.
+ * Props can be specified as an object or as a function that receives current props.
+ */
+export type Attrs<
+  TBaseProps,
+  TIn extends object = {},
+  TOut extends AttrsMerged<TBaseProps, TIn> = AttrsMerged<TBaseProps, TIn>,
+> = Partial<TOut> | AttrsFunction<TBaseProps, TIn, TOut>;
+
+/**
+ * Utility type to merge two object types, with properties from B taking precedence.
+ * If a property exists in both A and B, the property from B is used.
+ */
+export type Substitute<A extends object, B extends object> = FastOmit<A, keyof B> & B;
+
+/**
+ * Union type of all valid HTML element tag names.
+ * Derived from Solid's JSX intrinsic elements.
+ */
+export type HtmlTags = keyof JSX.IntrinsicElements;
+
+/**
+ * Custom web component tag pattern that must contain at least one hyphen.
+ * Follows the web component naming convention.
+ */
+export type CustomWebComponentTag = `${string}-${string}`;
+
+/**
+ * Utility type to efficiently remove properties from an object type.
+ * More performant than the built-in Omit type for large object types.
+ */
+export type FastOmit<T extends object, U extends string | number | symbol> = {
+  [K in keyof T as K extends U ? never : K]: T[K];
+};
+
+/**
+ * Set-like collector for class names.
+ *
+ * Implemented as a string builder in the runtime (a Set<string>
+ * split → Set → Array.from → join round-trip dominates render cost);
+ * a real Set<string> also satisfies this interface.
+ */
+export type ClassCollector = {
+  add(name: string): void;
+  has(name: string): boolean;
+  delete(name: string): void;
+};
+
+/**
+ * Type of all functions that can be passed to manipulate styles
+ *
+ * `$dynamic` marks processors that execute user functions or write style
+ * values at render time; purely static processors (class names only) can
+ * skip theme lookup and style-object allocation.
+ */
+export type RuntimeStyleProcessor<T> = ((
+  props: T,
+  classes: ClassCollector,
+  style: StyleObject,
+) => void) & { $dynamic?: boolean };
+
+/**
+ * Utility type to keep the generic API of a component while still being able to use it in a selector
+ */
+export type GenericYakComponentOf<T, P = {}> = T &
+  YakComponent<P> & {
+    <G = {}>(props: P & G): JSX.Element;
+  };