@teiler/svelte 0.0.30 → 0.1.0

package/README.md

@@ -4,9 +4,16 @@
 
 **Teiler** is an open source library that simplifies the creation of stylish components for various frameworks.
 
-Currently in the **alpha phase**, the library is actively being developed and improved. It currently provides support solely for Svelte CSR (Client-Side Rendering).
+Currently in the **alpha phase**, the library is actively being developed and improved. This package is the **Svelte 5** adapter and supports both CSR (Client-Side Rendering) and SSR (Server-Side Rendering).
 
-Join our community on our [Discord Server](https://discord.gg/J6Sv9sQ64t) to stay informed about the latest developments, exchange ideas, and connect with fellow developers. We are continuously working on expanding our support to include more frameworks, allowing developers to effortlessly create components across various environments. 
+Join our community on our [Discord Server](https://discord.gg/J6Sv9sQ64t) to stay informed about the latest developments, exchange ideas, and connect with fellow developers. We are continuously working on expanding our support to include more frameworks, allowing developers to effortlessly create components across various environments.
+
+## Requirements
+
+- `svelte` `^5.16.0`
+- A Svelte-aware bundler (Vite with `@sveltejs/vite-plugin-svelte`, SvelteKit, `rollup-plugin-svelte`, …)
+
+The package ships uncompiled `.svelte` files through the `svelte` export condition, so your bundler compiles them for the right target (client or server) with the same Svelte version as your application.
 
 ### Example
 
@@ -33,6 +40,19 @@ const Button = component.button<{
 `
 ```
 
+```svelte
+<Button _primary={primary} onclick={() => count++}>Clicked {count} times</Button>
+```
+
+Props prefixed with `_` are used only for styles and are not forwarded to the DOM. Every other prop, including event handlers (`onclick`, `oninput`, …) and `class`, is forwarded to the rendered element.
+
+## Migrating from Svelte 4 (`@teiler/svelte` 0.0.x)
+
+- Svelte 5 is required (`svelte` `^5.16.0`); Svelte 4 is no longer supported.
+- Event handlers are props: `<Button onclick={handler}>` instead of `<Button on:click={handler}>`.
+- If you provide the theme through context yourself, the `THEME` context holds a getter (`() => theme`) instead of a writable store. `ThemeProvider` usage is unchanged.
+- UMD/CJS bundles are gone; the package is consumed as Svelte source by your bundler.
+
 ## Keyframes
 
 ```typescript
@@ -90,31 +110,65 @@ const ButtonLink = component.a(Button)`
 `
 ```
 
-## Theme
+## `as` prop
 
-Example how to use themes.
+Use `as` to render a component as a different element or another component without creating a new styled component. Styles stay the same, `as` is not passed to the rendered element:
 
-```typescript
-// Main component inside application (`App.svelte`)
-<script context="module" lang="ts">
-  export type CustomTheme = {
-    fontColor: string,
-  }
+```svelte
+<script lang="ts">
+  import { Button } from './components'
+  import Link from './Link.svelte'
+</script>
+
+<Button as="a" href="/docs">Docs</Button>
+<Button as={Link} to="/home">Home</Button>
+```
+
+When `as` is a component, it receives `class`, `children` and every other forwarded prop. Svelte has no attribute fallthrough, so the component has to apply `class` to its root element:
+
+```svelte
+<!-- Link.svelte -->
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import type { ClassValue } from 'svelte/elements'
+
+  const { to, class: className, children }: { to: string; class?: ClassValue; children?: Snippet } = $props()
 </script>
+
+<a href={to} class={className}>{@render children?.()}</a>
+```
+
+Props are typed from `as`: `as="a"` accepts anchor attributes, `as={Link}` accepts the props of `Link` and requires its required props. Without `as`, the component accepts the attributes of its own element. `svelte-check` reports an unknown tag in `as` and attributes the target does not accept:
+
+```svelte
+<Button as="a" href="/docs">Docs</Button> <!-- ok -->
+<Button href="/docs">Docs</Button>        <!-- error: href is not a button attribute -->
+<Button as={Link}>Home</Button>           <!-- error: to is required -->
+```
+
+> [!NOTE]
+> `mount()` and `render()` called from TypeScript cannot infer `as`, so there props are typed from the element of the styled component.
+
+## Theme
+
+```svelte
+<!-- App.svelte -->
 <script lang="ts">
+  import type { CustomTheme } from './theme'
+
   import { ThemeProvider } from '@teiler/svelte'
-  import { Component } from './theme'
+  import { Component } from './components'
 
-  export let theme: CustomTheme = {
-    fontColor: 'red',
-  }
+  let theme: CustomTheme = $state({ fontColor: 'red' })
 </script>
 
 <ThemeProvider {theme}>
   <Component>Some test text</Component>
 </ThemeProvider>
+```
 
-// Component with theme usage
+```typescript
+// components.ts
 import { component } from '@teiler/svelte'
 
 const Component = component.div`
@@ -125,32 +179,76 @@ export { Component }
 ```
 
 To add typing for Typescript applications you need to add `extend` inside declaration file (`d.ts`)
+
 ```typescript
-import type { CustomTheme } from "./App.svelte";
+import type { CustomTheme } from './theme'
 
 declare module '@teiler/core' {
   export interface DefaultTheme extends CustomTheme {}
 }
 ```
 
+## Server-Side Rendering
+
+Styles are collected into a style sheet provided through the `STYLE_SHEET` context. Create one sheet per request, render, then put the extracted CSS into the document head.
+
+```typescript
+import { createStyleSheet } from '@teiler/core'
+import { render } from 'svelte/server'
+import App from './App.svelte'
+
+const sheet = createStyleSheet({})
+const { body } = render(App, { context: new Map([['STYLE_SHEET', sheet]]) })
+const { css, ids } = sheet.extract()
+
+const styleTag = `<style data-teiler="${ids.join(' ')}">${css}</style>`
+```
+
+Read `body` before calling `extract()`: styles are inserted while the component tree renders.
+
+> [!WARNING]
+> Always provide a style sheet through the `STYLE_SHEET` context on the server. Without it, every request shares one module-level style sheet, so styles accumulate across requests.
+
+## Hydration
+
+On the client, pass the ids rendered by the server to `hydrate`, so styles that are already in the document are not inserted again. Provide the same style sheet to the app through context:
+
+```typescript
+import { createStyleSheet } from '@teiler/core'
+import { hydrate } from 'svelte'
+import App from './App.svelte'
+
+const sheet = createStyleSheet({})
+const element = document.querySelector<HTMLStyleElement>('style[data-teiler]')
+
+sheet.hydrate(element?.dataset.teiler?.split(' ') ?? [])
+
+hydrate(App, { target: document.body, context: new Map([['STYLE_SHEET', sheet]]) })
+```
+
 ## Content Security Policy
 
-With a strict `style-src` policy, create the style sheet with a `nonce` and set it in the context of the main component. Without an explicit `nonce` no attribute is set, and the default style sheet never has one.
+With a strict `style-src` policy, pass a `nonce` to the style sheet and provide it through the `STYLE_SHEET` context. Without an explicit `nonce` no attribute is set, and the default style sheet never has one.
 
-```svelte
-<!-- Main component inside application (`App.svelte`) -->
-<script lang="ts">
-  import { createStyleSheet } from '@teiler/core'
-  import { setContext } from 'svelte'
+On the server, `extract` returns the nonce, so it can be set on the rendered `<style>` tag:
 
-  export let nonce: string
+```typescript
+const sheet = createStyleSheet({ nonce })
+const { body } = render(App, { context: new Map([['STYLE_SHEET', sheet]]) })
+const { css, ids } = sheet.extract()
 
-  setContext('STYLE_SHEET', createStyleSheet({ nonce }))
-</script>
+const styleTag = `<style data-teiler="${ids.join(' ')}" nonce="${nonce}">${css}</style>`
+```
+
+On the client, read the nonce from the server rendered tag before creating the style sheet:
+
+```typescript
+const element = document.querySelector<HTMLStyleElement>('style[data-teiler]')
+const sheet = createStyleSheet({ nonce: element?.nonce })
 ```
 
 > [!NOTE]
-> When reading the nonce from an existing element, use the `nonce` property, not `getAttribute('nonce')`. Browsers hide the attribute when the policy is sent in a header, so `getAttribute` returns an empty string.
+> Use the `nonce` property, not `getAttribute('nonce')`. Browsers hide the attribute when the policy is sent in a header, so `getAttribute` returns an empty string.
 
 ## Sew a Pattern
 

package/dist/Styled.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+  import type { DefaultTheme, HTMLElements, StyleDefinition } from '@teiler/core'
+  import type { Component, Snippet } from 'svelte'
+
+  import { clsx } from 'clsx'
+  import { insert } from '@teiler/core'
+  import { getStyleSheet } from './sheet.js'
+  import { getTheme } from './theme.js'
+
+  type Props = {
+    styleDefinition: StyleDefinition<HTMLElements, unknown>
+    as?: Exclude<HTMLElements, null> | Component<any>
+    class?: string
+    children?: Snippet
+    [key: string]: unknown
+  }
+
+  const { styleDefinition, as, class: className, children, ...props }: Props = $props()
+
+  const sheet = getStyleSheet()
+  const theme = getTheme()
+
+  const styleClassName = $derived(insert(sheet, styleDefinition, { ...props, theme: theme?.() ?? ({} as DefaultTheme) }))
+
+  const classes = $derived(clsx(styleClassName, styleDefinition.id, className))
+
+  const attributes = $derived(Object.fromEntries(Object.entries(props).filter(([key]) => key[0] !== '_')))
+</script>
+
+{#if styleClassName && styleDefinition.tag}
+  {@const Target = as ?? styleDefinition.tag}
+  {#if typeof Target === 'function'}
+    <Target class={classes} {...attributes} {children} />
+  {:else if children}
+    <svelte:element this={Target} class={classes} {...attributes}>{@render children()}</svelte:element>
+  {:else}
+    <svelte:element this={Target} class={classes} {...attributes} />
+  {/if}
+{/if}

package/dist/Styled.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { HTMLElements, StyleDefinition } from '@teiler/core';
+import type { Component, Snippet } from 'svelte';
+type Props = {
+    styleDefinition: StyleDefinition<HTMLElements, unknown>;
+    as?: Exclude<HTMLElements, null> | Component<any>;
+    class?: string;
+    children?: Snippet;
+    [key: string]: unknown;
+};
+declare const Styled: Component<Props, {}, "">;
+type Styled = ReturnType<typeof Styled>;
+export default Styled;

package/dist/ThemeProvider.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import type { DefaultTheme } from '@teiler/core'
+  import type { Snippet } from 'svelte'
+
+  import { setTheme } from './theme.js'
+
+  const { theme, children }: { theme: DefaultTheme; children?: Snippet } = $props()
+
+  setTheme(() => theme)
+</script>
+
+{@render children?.()}

package/dist/ThemeProvider.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { DefaultTheme } from '@teiler/core';
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    theme: DefaultTheme;
+    children?: Snippet;
+};
+declare const ThemeProvider: import("svelte").Component<$$ComponentProps, {}, "">;
+type ThemeProvider = ReturnType<typeof ThemeProvider>;
+export default ThemeProvider;

package/dist/component.d.ts

@@ -0,0 +1,36 @@
+import type { HTMLElements, Properties, StyleDefinition, TeilerComponent } from '@teiler/core';
+import type { ComponentConstructorOptions, ComponentInternals, Snippet, Component as SvelteComponent, SvelteComponent as SvelteComponentInstance } from 'svelte';
+import type { ClassValue, SvelteHTMLElements } from 'svelte/elements';
+import { keyframes } from '@teiler/core';
+type Tag = Exclude<HTMLElements, null>;
+type ElementProps<Target> = Target extends keyof SvelteHTMLElements ? SvelteHTMLElements[Target] : {};
+type AsTarget = Tag | SvelteComponent<never>;
+type TargetProps<As> = As extends SvelteComponent<infer Props> ? Omit<Props, 'class' | 'children'> & {
+    class?: ClassValue;
+    children?: Snippet;
+} : ElementProps<As>;
+type PolymorphicProps<Target extends HTMLElements, Props, As> = Props & {
+    as?: As;
+} & ([As] extends [never] ? ElementProps<Target> : [AsTarget] extends [As] ? ElementProps<Target> : TargetProps<As>);
+interface SvelteTeilerComponent<Target extends HTMLElements, Props extends object> extends TeilerComponent<Target, Props> {
+    <As extends AsTarget = never>(internals: ComponentInternals, props: PolymorphicProps<Target, Props, As>): {};
+    new <As extends AsTarget = never>(options: ComponentConstructorOptions<PolymorphicProps<Target, Props, As>>): SvelteComponentInstance<PolymorphicProps<Target, Props, As>>;
+}
+type SvelteGlobalComponent<Props extends object> = TeilerComponent<null, Props> & SvelteComponent<Props>;
+declare const createComponent: <Target extends HTMLElements, Props extends object = {}>(styleDefinition: StyleDefinition<Target, Props>) => SvelteTeilerComponent<Target, Props>;
+type InferProps<Component, Props> = Component extends TeilerComponent<HTMLElements, infer P> ? P & Props : Props;
+type InferComponent<Component, Props extends object, Extended> = Component extends TeilerComponent<infer E, infer P extends object> ? SvelteTeilerComponent<Extended extends HTMLElements ? Extended : E, Props & P> : SvelteTeilerComponent<HTMLElements, Props>;
+type Component<Target extends HTMLElements, Extended extends HTMLElements | undefined = Target> = {
+    <Props extends object = {}>(string: TemplateStringsArray, ...properties: Properties<Props>[]): SvelteTeilerComponent<Target, Props>;
+    <Component>(binded: Component): <Props extends object = {}>(string: TemplateStringsArray, ...properties: Properties<InferProps<Component, Props>>[]) => InferComponent<Component, Props, Extended>;
+};
+type Global = {
+    <Props extends object = {}>(string: TemplateStringsArray, ...properties: Properties<Props>[]): SvelteGlobalComponent<Props>;
+};
+type ComponentWithTags = Component<'div', undefined> & {
+    [K in Exclude<HTMLElements, null>]: Component<K>;
+};
+declare const svelteComponent: ComponentWithTags;
+declare const svelteGlobal: Global;
+export type { SvelteGlobalComponent, SvelteTeilerComponent };
+export { svelteComponent as component, svelteGlobal as global, keyframes, createComponent };

package/dist/component.js

@@ -0,0 +1,25 @@
+import { component, global, keyframes, styled, tags } from '@teiler/core';
+import Styled from './Styled.svelte';
+const withStyleDefinition = (props, styleDefinition) => {
+    return new Proxy(props, {
+        get: (target, key) => (key === 'styleDefinition' ? styleDefinition : Reflect.get(target, key)),
+        has: (target, key) => key === 'styleDefinition' || Reflect.has(target, key),
+    });
+};
+const createComponent = (styleDefinition) => {
+    const wrapped = (internals, props) => Styled(internals, withStyleDefinition(props, styleDefinition));
+    return Object.assign(wrapped, { styleDefinition });
+};
+const construct = (tag, compiler) => {
+    return (stringOrBinded, ...properties) => {
+        return styled(tag, compiler, createComponent, stringOrBinded, ...properties);
+    };
+};
+const svelteComponent = construct(undefined, component);
+tags.forEach((tag) => {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error
+    svelteComponent[tag] = construct(tag, component);
+});
+const svelteGlobal = construct(null, global);
+export { svelteComponent as component, svelteGlobal as global, keyframes, createComponent };

package/{src/index.ts → dist/index.d.ts}

@@ -1,2 +1,2 @@
-export { component, global, keyframes, createComponent } from './component'
-export { default as ThemeProvider } from './ThemeProvider.svelte'
+export { component, global, keyframes, createComponent } from './component.js';
+export { default as ThemeProvider } from './ThemeProvider.svelte';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { component, global, keyframes, createComponent } from './component.js';
+export { default as ThemeProvider } from './ThemeProvider.svelte';

package/dist/sheet.d.ts

@@ -0,0 +1,4 @@
+import { type Sheet } from '@teiler/core';
+export declare let styleSheet: Sheet | null;
+export declare const StyleSheet = "STYLE_SHEET";
+export declare function getStyleSheet(): Sheet;

package/dist/sheet.js

@@ -0,0 +1,14 @@
+import { createStyleSheet } from '@teiler/core';
+import { getContext } from 'svelte';
+export let styleSheet = null;
+export const StyleSheet = 'STYLE_SHEET';
+export function getStyleSheet() {
+    const fromContext = getContext(StyleSheet);
+    if (fromContext) {
+        return fromContext;
+    }
+    if (styleSheet === null) {
+        styleSheet = createStyleSheet({});
+    }
+    return styleSheet;
+}

package/dist/theme.d.ts

@@ -0,0 +1,5 @@
+import type { DefaultTheme } from '@teiler/core';
+export declare const Theme = "THEME";
+export type ThemeGetter = () => DefaultTheme;
+export declare function setTheme(theme: ThemeGetter): void;
+export declare function getTheme(): ThemeGetter | undefined;

package/dist/theme.js

@@ -0,0 +1,8 @@
+import { getContext, setContext } from 'svelte';
+export const Theme = 'THEME';
+export function setTheme(theme) {
+    setContext(Theme, theme);
+}
+export function getTheme() {
+    return getContext(Theme);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teiler/svelte",
-  "version": "0.0.30",
+  "version": "0.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nerdslabs/teiler.git",
@@ -8,53 +8,54 @@
   },
   "homepage": "https://github.com/nerdslabs/teiler/tree/master/packages/svelte#readme",
   "type": "module",
-  "main": "dist/teiler-svelte.cjs.js",
-  "module": "./dist/teiler-svelte.esm.js",
-  "types": "./dist/teiler-svelte.d.ts",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/teiler-svelte.esm.js",
-      "require": "./dist/teiler-svelte.cjs.ts",
-      "types": "./dist/teiler-svelte.d.ts"
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.fixture.*"
+  ],
   "dependencies": {
-    "@teiler/core": "0.1.0"
+    "@teiler/core": "0.1.0",
+    "clsx": "^2.1.1"
   },
   "peerDependencies": {
-    "svelte": "^4.0.0"
+    "svelte": "^5.16.0"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^3.2.7",
-    "@storybook/addon-essentials": "^8.6.18",
-    "@storybook/addon-interactions": "^8.6.18",
-    "@storybook/addon-links": "^8.6.18",
-    "@storybook/blocks": "^8.6.18",
-    "@storybook/svelte": "^8.6.18",
-    "@storybook/svelte-vite": "^8.6.18",
-    "@storybook/test": "^8.6.18",
-    "@storybook/test-runner": "0.24.4",
-    "@sveltejs/vite-plugin-svelte": "^3.1.2",
-    "@swc/core": "^1.16.2",
-    "@swc/jest": "^0.2.39",
-    "@testing-library/svelte": "^4.2.3",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "rolldown": "^1.2.11",
-    "rolldown-plugin-dts": "^0.28.6",
-    "storybook": "^8.6.18",
-    "svelte": "^4.2.20",
-    "svelte-jester": "^5.0.0",
-    "svelte-loader": "^3.2.4",
-    "svelte-preprocess": "^5.1.4",
-    "typescript": "^5.8.3"
+    "@chromatic-com/storybook": "^5.3.1",
+    "@storybook/addon-links": "^10.6.0",
+    "@storybook/addon-vitest": "^10.6.0",
+    "@storybook/svelte": "^10.6.0",
+    "@storybook/svelte-vite": "^10.6.0",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@testing-library/svelte": "^5.4.2",
+    "@vitest/browser-playwright": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.11",
+    "jsdom": "^30.1.1",
+    "playwright": "^1.63.0",
+    "storybook": "^10.6.0",
+    "svelte": "^5.57.1",
+    "svelte-check": "^4.7.6",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.1",
+    "vitest": "^4.1.11"
   },
   "scripts": {
-    "build": "rolldown --config",
-    "dev": "rolldown --config --watch",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "build": "svelte-package -i src -o dist",
+    "dev": "svelte-package -i src -o dist --watch",
+    "test": "vitest run --project client --project server",
+    "typecheck": "node scripts/typecheck.js",
     "storybook": "storybook dev -p 6006 --no-open",
-    "storybook-test": "test-storybook --url http://localhost:6006",
+    "storybook-test": "vitest run --project storybook",
     "build-storybook": "storybook build"
   }
 }

package/.npmignore

@@ -1,5 +0,0 @@
-.turbo
-.storybook
-node_modules
-stories
-rollup.config.js