@teiler/svelte 0.0.29 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-present, NERDSLABS
+
+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

@@ -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
@@ -67,31 +87,88 @@ const Button = component.button<{}>`
 `
 ```
 
-## Theme
+## Extending
 
-Example how to use themes.
+Pass an existing component to `component` to add styles to it. The new component keeps the element of the extended one, unless you pick another element with `component.<tag>`:
 
 ```typescript
-// Main component inside application (`App.svelte`)
-<script context="module" lang="ts">
-  export type CustomTheme = {
-    fontColor: string,
-  }
+import { component } from '@teiler/svelte'
+
+const Button = component.button`
+  display: inline-block;
+  border-radius: 4px;
+`
+
+// renders <button>
+const PrimaryButton = component(Button)`
+  background: #CBCBCB;
+`
+
+// renders <a> with Button styles
+const ButtonLink = component.a(Button)`
+  text-decoration: none;
+`
+```
+
+## `as` prop
+
+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:
+
+```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`
@@ -102,14 +179,77 @@ 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, 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.
+
+On the server, `extract` returns the nonce, so it can be set on the rendered `<style>` tag:
+
+```typescript
+const sheet = createStyleSheet({ nonce })
+const { body } = render(App, { context: new Map([['STYLE_SHEET', sheet]]) })
+const { css, ids } = sheet.extract()
+
+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]
+> 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
 
 This tool simplifies the creation of consistent and reusable visual styles for components across various web frameworks. It provides a pattern-based approach, where patterns serve as blueprints for defining the visual style of components.
@@ -140,3 +280,17 @@ const Button = sew(ButtonPattern, createComponent)
 
 export default Button
 ```
+
+Patterns can be extended the same way as components. `pattern(ButtonPattern)` keeps the element of the extended pattern, `pattern.<tag>(ButtonPattern)` changes it:
+
+```typescript
+import { pattern } from '@teiler/core'
+
+const PrimaryButtonPattern = pattern(ButtonPattern)`
+  background: #CBCBCB;
+`
+
+const ButtonLinkPattern = pattern.a(ButtonPattern)`
+  text-decoration: none;
+`
+```

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,63 +1,61 @@
 {
   "name": "@teiler/svelte",
-  "version": "0.0.29",
+  "version": "0.1.0",
   "repository": {
-    "url": "nerdslabs/teiler",
+    "type": "git",
+    "url": "git+https://github.com/nerdslabs/teiler.git",
     "directory": "packages/svelte"
   },
   "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"
     }
   },
-  "scripts": {
-    "build": "rollup --config --bundleConfigAsCjs",
-    "dev": "rollup --config --bundleConfigAsCjs --watch",
-    "test": "node --experimental-vm-modules $(yarn bin jest)",
-    "storybook": "storybook dev -p 6006 --no-open",
-    "storybook-test": "test-storybook --url http://localhost:6006",
-    "build-storybook": "storybook build"
-  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.fixture.*"
+  ],
   "dependencies": {
-    "@teiler/core": "0.0.28",
-    "svelte": "^4.2.20"
+    "@teiler/core": "0.1.0",
+    "clsx": "^2.1.1"
+  },
+  "peerDependencies": {
+    "svelte": "^5.16.0"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^3.2.7",
-    "@rollup/plugin-commonjs": "^28.0.6",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^15.3.1",
-    "@rollup/plugin-swc": "^0.4.0",
-    "@storybook/addon-essentials": "^8.6.14",
-    "@storybook/addon-interactions": "^8.6.14",
-    "@storybook/addon-links": "^8.6.14",
-    "@storybook/blocks": "^8.6.14",
-    "@storybook/svelte": "^8.6.14",
-    "@storybook/svelte-vite": "^8.6.14",
-    "@storybook/test": "^8.6.14",
-    "@storybook/test-runner": "0.19.1",
-    "@sveltejs/vite-plugin-svelte": "^3.1.2",
-    "@swc/core": "^1.13.2",
-    "@swc/jest": "^0.2.39",
-    "@testing-library/svelte": "^5.2.8",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "jsdom": "^25.0.1",
-    "rollup": "^4.45.1",
-    "rollup-plugin-dts": "^6.2.1",
-    "rollup-plugin-svelte": "^7.2.2",
-    "rollup-plugin-terser": "^7.0.2",
-    "storybook": "^8.6.14",
-    "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": "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": "vitest run --project storybook",
+    "build-storybook": "storybook build"
   }
-}
+}