@awc-ui/svelte 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -1,55 +1,62 @@
-# @awc-ui/svelte
+# Svelte Web Components and SvelteKit SSR — @awc-ui/svelte
 
-Svelte bindings for [AWC UI](https://www.npmjs.com/package/@awc-ui/core) — Material Design 3 web components.
-
-## Install
+`@awc-ui/svelte` supplies types for AWC UI's native custom elements in Svelte 4
+and 5. Property types and custom-event payloads come from the core declarations.
 
 ```bash
-npm install @awc-ui/svelte @awc-ui/core @awc-ui/tokens
+npm install @awc-ui/svelte @awc-ui/core
 ```
 
-Requires Svelte 4 or 5.
-
-## Usage
-
-Register the custom elements once on the client, then use `md-*` tags directly in any `.svelte` file — Svelte has first-class custom-element support, so no per-component wrappers are needed:
+For a client-rendered Vite application, load the theme and register the components
+you use through static imports. Import the Svelte package's types once:
 
 ```ts
-// main.ts (plain Vite/SPA app)
-import { defineCustomElements } from '@awc-ui/svelte';
-defineCustomElements(window);
-```
-
-```svelte
-<md-button variant="filled" on:click={save}>Save</md-button>
-<md-text-field label="Email" variant="outlined"></md-text-field>
+// main.ts
+import type {} from '@awc-ui/svelte';
+import '@awc-ui/core/css/tokens.css';
+import '@awc-ui/core/components/md-text-field';
+import '@awc-ui/core/components/md-button';
 ```
 
-### SvelteKit (SSR)
-
-Registration is client-only — guard it so it runs in the browser:
+Then use the native properties and custom events directly:
 
-```ts
-import { browser } from '$app/environment';
-import { defineCustomElements } from '@awc-ui/svelte';
-
-if (browser) defineCustomElements(window);
-```
-
-For server-rendered markup use `@awc-ui/core/hydrate` (`renderToString`).
-
-## Styling
-
-Load the design tokens once (they carry the whole MD3 theme):
-
-```ts
-import '@awc-ui/tokens/tokens.css';
+```svelte
+<script lang="ts">
+  let name = '';
+</script>
+
+<md-text-field
+  label="Project name"
+  value={name}
+  on:mdInput={(event) => name = event.detail}
+></md-text-field>
+<md-button variant="filled">Create project</md-button>
 ```
 
-## Docs
-
-Full component reference, theming, and framework setup: **[awc-ui.dev](https://awc-ui.dev)** — see [Installation](https://awc-ui.dev/getting-started/installation/) for the Svelte section.
-
-## License
-
-MIT
+The `mdInput` payload is inferred as a string, and invalid component property
+values are reported by `svelte-check`. Svelte 5 also supports the event-handler
+property spelling `onmdInput`. Use `value` plus the component's `mdInput` or
+`mdChange` event to synchronize forms; the custom elements do not expose a
+Svelte `bind:value` contract.
+
+`defineCustomElements` remains available from `@awc-ui/svelte` for applications
+that deliberately deploy the lazy loader and its runtime chunks. Static component
+imports work with Vite's module graph and keep registration limited to the
+components you use.
+
+## SvelteKit server-side rendering
+
+Use SvelteKit 2.10 or later for the client initialization hook. On the server,
+transform the completed HTML response with `renderToString` from
+`@awc-ui/core/hydrate`; `createPageTransform` from `@awc-ui/core/ssr/sveltekit`
+buffers response chunks until the document is complete.
+
+On the client, create a shared `createSvelteHydration()` instance from
+`@awc-ui/core/ssr/sveltekit`. Call `capture()` from `hooks.client.ts`'s `init`
+before Svelte hydrates, then call `restore()` in the root layout's `onMount`
+before dynamically importing the SSR-capable component entries. This preserves
+AWC shadow roots while Svelte claims the surrounding document.
+
+The helper must come from the same AWC UI release as the core components. Follow
+the complete [SvelteKit reference app](https://github.com/awc-ui/core/tree/main/apps/example-sveltekit)
+and [shared SSR guide](https://awc-ui.dev/frameworks/ssr/) for the server hook and client lifecycle.

package/dist/index.d.ts

@@ -1,23 +1,16 @@
 /**
- * @awc-ui/svelte
+ * Svelte 4/5 custom-element types and optional lazy-loader registration.
  *
- * Svelte integration for AWC UI Material Design 3 components.
- *
- * Registration is client-only. In a plain Vite/SPA app:
- * @example
- * import { defineCustomElements } from '@awc-ui/svelte';
- * defineCustomElements(window);
- *
- * Under SvelteKit (SSR), guard it so it runs only in the browser — and for
- * server-rendered markup use `@awc-ui/core/hydrate` (`renderToString`):
+ * In a client-rendered Vite app, load types and statically register what you use:
  * @example
- * import { browser } from '$app/environment';
- * import { defineCustomElements } from '@awc-ui/svelte';
- * if (browser) defineCustomElements(window);
+ * import type {} from '@awc-ui/svelte';
+ * import '@awc-ui/core/css/tokens.css';
+ * import '@awc-ui/core/components/md-button';
  *
- * Then use components directly in .svelte files:
- * @example
- * <md-button variant="filled">Click me</md-button>
+ * Under SvelteKit, use @awc-ui/core/ssr/sveltekit to preserve server-rendered
+ * shadow roots, then dynamically import components after Svelte hydrates.
+ * See the Svelte framework guide for the complete client/server lifecycle.
  */
-export * from './lib/components';
+export * from './lib/components.js';
+export type { AwcElementAttributes } from './lib/elements.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,qBAAqB,CAAC;AACpC,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/lib/elements.d.ts

@@ -0,0 +1,26 @@
+import type { JSX as AwcJSX } from '@awc-ui/core';
+import type { HTMLAttributes } from 'svelte/elements';
+/** AWC event payloads, property types and their default HTML attribute spellings. */
+type KebabCase<S extends string> = S extends `${infer First}${infer Rest}` ? `${First extends Lowercase<First> ? First : `-${Lowercase<First>}`}${KebabCase<Rest>}` : S;
+type ComponentAttributes<Props> = Omit<HTMLAttributes<HTMLElement>, keyof Props> & {
+    [Key in keyof Props as Key extends `on${string}` ? never : Key]: Props[Key];
+} & {
+    [Key in keyof Props as Key extends string ? Key extends `on${string}` ? never : KebabCase<Key> : never]: Props[Key];
+} & {
+    [Key in keyof Props as Key extends `on${infer Event}` ? `on:${Uncapitalize<Event>}` | `on${Uncapitalize<Event>}` : never]: Props[Key];
+};
+export type AwcElementAttributes = {
+    [Tag in keyof AwcJSX.IntrinsicElements]: ComponentAttributes<AwcJSX.IntrinsicElements[Tag]>;
+};
+declare module 'svelte/elements' {
+    interface SvelteHTMLElements extends AwcElementAttributes {
+    }
+}
+declare global {
+    namespace svelteHTML {
+        interface IntrinsicElements extends AwcElementAttributes {
+        }
+    }
+}
+export {};
+//# sourceMappingURL=elements.d.ts.map

package/dist/lib/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../src/lib/elements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,IAAI,MAAM,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,qFAAqF;AACrF,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,GACtE,GAAG,KAAK,SAAS,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,GACtF,CAAC,CAAC;AAEN,KAAK,mBAAmB,CAAC,KAAK,IAAI,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAC,GAC5E;KAAG,GAAG,IAAI,MAAM,KAAK,IAAI,GAAG,SAAS,KAAK,MAAM,EAAE,GAAG,KAAK,GAAG,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;CAAE,GAC/E;KAAG,GAAG,IAAI,MAAM,KAAK,IAAI,GAAG,SAAS,MAAM,GAAG,GAAG,SAAS,KAAK,MAAM,EAAE,GAAG,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC;CAAE,GACvH;KAAG,GAAG,IAAI,MAAM,KAAK,IAAI,GAAG,SAAS,KAAK,MAAM,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,YAAY,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC;CAAE,CAAC;AAE9I,MAAM,MAAM,oBAAoB,GAAG;KAChC,GAAG,IAAI,MAAM,MAAM,CAAC,iBAAiB,GAAG,mBAAmB,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;CAC5F,CAAC;AAIF,OAAO,QAAQ,iBAAiB,CAAC;IAC/B,UAAU,kBAAmB,SAAQ,oBAAoB;KAAG;CAC7D;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU,CAAC;QACnB,UAAU,iBAAkB,SAAQ,oBAAoB;SAAG;KAC5D;CACF"}

package/package.json

@@ -1,17 +1,37 @@
 {
   "name": "@awc-ui/svelte",
-  "version": "1.0.0-beta.1",
-  "description": "Svelte wrapper for AWC UI Material Design 3 components",
+  "version": "1.0.0-beta.11",
+  "description": "Svelte 4 and 5 components for accessible Material Design 3 Web Components, with SvelteKit SSR and server-rendering guidance",
   "keywords": [
     "svelte",
+    "svelte-component",
     "svelte-components",
+    "components",
     "material-design",
     "material-design-3",
     "md3",
     "ui-components",
     "component-library",
     "web-components",
-    "design-system"
+    "design-system",
+    "material-3",
+    "svelte-ui",
+    "custom-elements",
+    "typescript",
+    "accessibility",
+    "wcag",
+    "sveltekit",
+    "ssr",
+    "ui-library",
+    "svelte5",
+    "svelte-5",
+    "svelte-ui-library",
+    "svelte-ui-components",
+    "svelte-component-library",
+    "web-component",
+    "svelte-web-components",
+    "sveltekit-components",
+    "server-side-rendering"
   ],
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -28,12 +48,12 @@
   ],
   "peerDependencies": {
     "svelte": ">=4",
-    "@awc-ui/core": "1.0.0-beta.1"
+    "@awc-ui/core": "1.0.0-beta.11"
   },
   "devDependencies": {
     "esbuild": "^0.25.12",
     "typescript": "^5.4.0",
-    "@awc-ui/core": "1.0.0-beta.1"
+    "@awc-ui/core": "1.0.0-beta.11"
   },
   "license": "MIT",
   "author": "AWC UI",
@@ -53,6 +73,7 @@
   },
   "type": "module",
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --target=es2020 --sourcemap --outfile=dist/index.mjs --external:svelte --external:@awc-ui/core --external:@awc-ui/core/*"
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --target=es2020 --sourcemap --outfile=dist/index.mjs --external:svelte --external:@awc-ui/core --external:@awc-ui/core/*",
+    "test:integration": "node tests/types.mjs"
   }
 }

package/src/index.ts

@@ -1,22 +1,15 @@
 /**
- * @awc-ui/svelte
+ * Svelte 4/5 custom-element types and optional lazy-loader registration.
  *
- * Svelte integration for AWC UI Material Design 3 components.
- *
- * Registration is client-only. In a plain Vite/SPA app:
- * @example
- * import { defineCustomElements } from '@awc-ui/svelte';
- * defineCustomElements(window);
- *
- * Under SvelteKit (SSR), guard it so it runs only in the browser — and for
- * server-rendered markup use `@awc-ui/core/hydrate` (`renderToString`):
+ * In a client-rendered Vite app, load types and statically register what you use:
  * @example
- * import { browser } from '$app/environment';
- * import { defineCustomElements } from '@awc-ui/svelte';
- * if (browser) defineCustomElements(window);
+ * import type {} from '@awc-ui/svelte';
+ * import '@awc-ui/core/css/tokens.css';
+ * import '@awc-ui/core/components/md-button';
  *
- * Then use components directly in .svelte files:
- * @example
- * <md-button variant="filled">Click me</md-button>
+ * Under SvelteKit, use @awc-ui/core/ssr/sveltekit to preserve server-rendered
+ * shadow roots, then dynamically import components after Svelte hydrates.
+ * See the Svelte framework guide for the complete client/server lifecycle.
  */
-export * from './lib/components';
+export * from './lib/components.js';
+export type { AwcElementAttributes } from './lib/elements.js';

package/src/lib/elements.ts

@@ -0,0 +1,28 @@
+import type { JSX as AwcJSX } from '@awc-ui/core';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** AWC event payloads, property types and their default HTML attribute spellings. */
+type KebabCase<S extends string> = S extends `${infer First}${infer Rest}`
+  ? `${First extends Lowercase<First> ? First : `-${Lowercase<First>}`}${KebabCase<Rest>}`
+  : S;
+
+type ComponentAttributes<Props> = Omit<HTMLAttributes<HTMLElement>, keyof Props>
+  & { [Key in keyof Props as Key extends `on${string}` ? never : Key]: Props[Key] }
+  & { [Key in keyof Props as Key extends string ? Key extends `on${string}` ? never : KebabCase<Key> : never]: Props[Key] }
+  & { [Key in keyof Props as Key extends `on${infer Event}` ? `on:${Uncapitalize<Event>}` | `on${Uncapitalize<Event>}` : never]: Props[Key] };
+
+export type AwcElementAttributes = {
+  [Tag in keyof AwcJSX.IntrinsicElements]: ComponentAttributes<AwcJSX.IntrinsicElements[Tag]>;
+};
+
+// Current Svelte 4 and 5 tooling reads svelte/elements; older Svelte 4 tooling
+// reads the global namespace. Both derive from the same core declarations.
+declare module 'svelte/elements' {
+  interface SvelteHTMLElements extends AwcElementAttributes {}
+}
+
+declare global {
+  namespace svelteHTML {
+    interface IntrinsicElements extends AwcElementAttributes {}
+  }
+}