sv5ui 2.1.0 → 2.3.0

package/README.md

@@ -5,113 +5,192 @@
 <h1 align="center">SV5UI</h1>
 
 <p align="center">
-  <strong>Modern UI component library for Svelte 5</strong><br/>
-  Tailwind CSS 4 &middot; OKLCH Color Tokens &middot; Fully Typed &middot; 50+ Components &middot; 7 Hooks
+  <strong>The modern UI component library for Svelte 5.</strong><br/>
+  Accessible components and reactive hooks, styled with Tailwind CSS 4 and fully typed.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/sv5ui"><img src="https://img.shields.io/npm/v/sv5ui?style=flat-square&colorA=18181b&colorB=ff3e00" alt="npm" /></a>
-  <a href="https://www.npmjs.com/package/sv5ui"><img src="https://img.shields.io/npm/dm/sv5ui?style=flat-square&colorA=18181b&colorB=ff3e00" alt="downloads" /></a>
+  <a href="https://www.npmjs.com/package/sv5ui"><img src="https://img.shields.io/npm/v/sv5ui?style=flat-square&colorA=18181b&colorB=ff3e00" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/sv5ui"><img src="https://img.shields.io/npm/dm/sv5ui?style=flat-square&colorA=18181b&colorB=ff3e00" alt="npm downloads" /></a>
   <a href="https://github.com/ndlabdev/sv5ui/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/sv5ui?style=flat-square&colorA=18181b&colorB=ff3e00" alt="license" /></a>
 </p>
 
 <p align="center">
-  <a href="https://sv5ui.vercel.app"><strong>Live Demo</strong></a> &middot;
-  <a href="https://sv5ui.vercel.app/getting-started"><strong>Getting Started</strong></a> &middot;
+  <a href="https://sv5ui.vercel.app"><strong>Live Demo &amp; Docs</strong></a> &middot;
   <a href="https://github.com/ndlabdev/sv5ui/blob/main/CHANGELOG.md"><strong>Changelog</strong></a>
 </p>
 
 ---
 
-## Install
+**SV5UI** is a batteries-included component library built natively for **Svelte 5 runes**. It pairs accessible primitives from [Bits UI](https://bits-ui.com) with a [Tailwind CSS 4](https://tailwindcss.com) styling layer you can theme down to a single token — so you ship polished, accessible UI without rebuilding buttons, modals, and forms for the hundredth time.
+
+```svelte
+<script>
+    import { Button, Avatar, toast } from 'sv5ui'
+</script>
+
+<Button variant="soft" color="primary" leadingIcon="lucide:edit">Edit</Button>
+<Avatar src="/photo.jpg" alt="Jane" size="lg" />
+<Button onclick={() => toast.success('Saved!')}>Save</Button>
+```
+
+## Why SV5UI?
+
+- **Native Svelte 5** — Built on runes and snippets from the ground up, not ported from an older API. Reactivity is first-class, not retrofitted.
+- **Accessible by default** — Overlays, menus, and form controls are built on [Bits UI](https://bits-ui.com) and [Vaul Svelte](https://vaul-svelte.com), so focus management, keyboard navigation, and WAI-ARIA semantics come for free.
+- **Thoroughly tested** — Every component is covered by an extensive unit and real-browser test suite (Vitest + Playwright), including accessibility and memory-leak regressions.
+- **Themeable to the core** — [OKLCH](https://oklch.com) color tokens, automatic light/dark mode, and three layers of customization (per-instance → global config → CSS variables).
+- **Truly typed** — Strict TypeScript with exported prop types for every component; a `publint`-clean ESM package with proper `types` and `svelte` export conditions.
+- **Tree-shakeable** — Pure ESM with side effects limited to CSS, so you only ship the components you import.
+- **Bring your own validation** — `Form` speaks [Standard Schema](https://standardschema.dev), so it works out of the box with Zod, Valibot, Yup, or Joi.
+- **Icons included** — Reference any [Iconify](https://iconify.design) icon by name, with no per-icon imports: `leadingIcon="lucide:edit"`.
+
+## Quick Start
+
+**1. Install**
 
 ```bash
 npm install sv5ui
-# pnpm add sv5ui
-# yarn add sv5ui
-# bun add sv5ui
+# pnpm add sv5ui · yarn add sv5ui · bun add sv5ui
 ```
 
+> **Peer dependencies:** `svelte@^5`, `tailwindcss@^4`, and `mode-watcher@^1`. The rich-text `Editor` and `Form` validators (TipTap, Zod/Valibot/Yup/Joi) are **optional** peers — install only what you use.
+
+**2. Import the theme**
+
 ```css
-/* layout.css */
+/* app.css */
 @import 'sv5ui/theme.css';
 ```
 
+**3. Enable dark mode** (one-time, in your root layout)
+
 ```svelte
 <script>
-    import { Button, Avatar, toast } from 'sv5ui'
+    import { ModeWatcher } from 'mode-watcher'
 </script>
 
-<Button variant="soft" color="primary" leadingIcon="lucide:edit">Edit</Button>
-<Avatar src="/photo.jpg" alt="Jane" size="lg" />
+<ModeWatcher />
+```
+
+**4. Use components**
+
+```svelte
+<script>
+    import { Card, Button } from 'sv5ui'
+</script>
+
+<Card>
+    <p>Welcome back 👋</p>
+    <Button color="primary" leadingIcon="lucide:log-in">Sign in</Button>
+</Card>
 ```
 
-## Features
+That's it — no provider to wrap, no config file required.
+
+## Components
 
-- **Svelte 5** — Runes, snippets, latest reactivity
-- **Tailwind CSS 4** — Utility-first with [Tailwind Variants](https://www.tailwind-variants.org/)
-- **Fully Typed** — Strict TypeScript, exported prop types
-- **Accessible** — Built on [Bits UI](https://bits-ui.com) & [Vaul Svelte](https://vaul-svelte.com)
-- **200,000+ Icons** — [Iconify](https://iconify.design) integration
-- **Themeable** — OKLCH color tokens, light/dark mode, global config
-- **Hooks** — 7 reactive hooks for common UI patterns
+SV5UI covers the surface area of a real application — forms and inputs, overlays and menus, navigation, data display, and feedback — including richer pieces many libraries leave out, like a TipTap-powered rich-text **Editor**, a data **Table**, a **Command** palette, and a **Calendar**.
+
+Every component is fully typed, theme-aware, and exposes a consistent `variant` / `color` / `size` / `ui` API. Browse the complete, always-current catalog with live examples and prop tables in the **[live demo](https://sv5ui.vercel.app)**.
 
 ## Hooks
 
-Reactive hooks built on Svelte 5 runes and actions.
+Beyond components, SV5UI exports a set of reactive hooks — built on the same runes and actions it uses internally — for everyday UI needs such as media queries, clipboard access, debouncing, focus trapping, and scroll locking.
 
 ```svelte
 <script>
-    import { useMediaQuery, useClipboard, useDebounce } from 'sv5ui'
+    import { useMediaQuery, useClipboard } from 'sv5ui'
 
     const isMobile = useMediaQuery('(max-width: 640px)')
     const clipboard = useClipboard()
-    const debounce = useDebounce({ delay: 500 })
 </script>
 
-{#if isMobile.matches}
-    <MobileLayout />
-{/if}
+{#if isMobile.matches}<MobileNav />{/if}
 
 <Button onclick={() => clipboard.copy('Hello!')}>
     {clipboard.copied ? 'Copied!' : 'Copy'}
 </Button>
 ```
 
-| Hook                | Type           | Description                                    |
-| ------------------- | -------------- | ---------------------------------------------- |
-| `useMediaQuery`     | Runes          | Reactive CSS media query tracking              |
-| `useClipboard`      | Runes          | Copy text with auto-reset state                |
-| `useFormField`      | Context        | Access FormField context from child components |
-| `useDebounce`       | Runes          | Debounce with pending, cancel, flush           |
-| `useClickOutside`   | Action         | Detect clicks outside an element               |
-| `useInfiniteScroll` | Runes + Action | Auto-load on scroll with loading state         |
-| `useEscapeKeydown`  | Action         | Listen for Escape key                          |
-
 ## Customization
 
+SV5UI gives you three layers of control, from a single instance up to your whole design system.
+
+**1. Per-instance** — override any slot with the `ui` prop or `class`:
+
 ```svelte
-<!-- Per-instance -->
-<Button ui={{ base: 'rounded-full shadow-lg' }}>Custom</Button>
+<Button ui={{ base: 'rounded-full shadow-lg' }}>Pill button</Button>
 ```
 
+**2. Global defaults** — set library-wide variants and icons once:
+
 ```ts
-// Global defaults
 import { defineConfig } from 'sv5ui'
 
 defineConfig({
     button: { defaultVariants: { variant: 'outline' } },
-    icons: { loading: 'lucide:loader' }
+    icons: { loading: 'lucide:loader-circle' }
 })
 ```
 
+**3. Design tokens** — re-skin everything with CSS variables (OKLCH):
+
 ```css
-/* Custom colors */
 :root {
     --color-primary: oklch(0.55 0.25 270);
+    --radius-lg: 0.75rem;
 }
 ```
 
+## Form validation
+
+`Form` validates with any [Standard Schema](https://standardschema.dev) library — no adapter, no wrapper:
+
+```svelte
+<script>
+    import { Form, FormField, Input, Button } from 'sv5ui'
+    import { z } from 'zod'
+
+    const schema = z.object({
+        email: z.string().email(),
+        password: z.string().min(8)
+    })
+</script>
+
+<Form {schema} onsubmit={({ data }) => console.log(data)}>
+    <FormField name="email" label="Email"><Input /></FormField>
+    <FormField name="password" label="Password"><Input type="password" /></FormField>
+    <Button type="submit">Sign in</Button>
+</Form>
+```
+
+Swap `zod` for `valibot`, `yup`, or `joi` — the API is identical.
+
+## Requirements
+
+| Peer                              | Version  | Required                   |
+| --------------------------------- | -------- | -------------------------- |
+| `svelte`                          | `^5.0.0` | Yes                        |
+| `tailwindcss`                     | `^4.0.0` | Yes                        |
+| `mode-watcher`                    | `^1.0.0` | Yes (dark mode)            |
+| `zod` / `valibot` / `yup` / `joi` | —        | Optional (form validation) |
+| `@tiptap/*`, `tiptap-markdown`    | `^3.0.0` | Optional (`Editor`)        |
+
+## Contributing
+
+Issues and pull requests are welcome. To run the project locally:
+
+```bash
+git clone https://github.com/ndlabdev/sv5ui.git
+cd sv5ui
+npm install
+npm run dev        # docs site at localhost:5173
+npm test           # vitest (unit + browser)
+npm run check      # svelte-check
+npm run lint       # prettier + eslint
+```
+
 ## License
 
 [MIT](LICENSE) &copy; [ndlabdev](https://github.com/ndlabdev)

package/dist/{Accordion → components/Accordion}/Accordion.svelte

@@ -1,102 +1,82 @@
-<script lang="ts" module>
-    import type { AccordionProps, AccordionItem } from './accordion.types.js'
-
-    export type Props = AccordionProps
-</script>
-
-<script lang="ts">
-    import { Accordion } from 'bits-ui'
-    import { slide } from 'svelte/transition'
-    import { accordionVariants, accordionDefaults } from './accordion.variants.js'
-    import { getComponentConfig } from '../config.js'
-    import Icon from '../Icon/Icon.svelte'
-
-    const config = getComponentConfig('accordion', accordionDefaults)
-
-    let {
-        items = [],
-        type = 'single',
-        value = $bindable(),
-        onValueChange,
-        disabled = false,
-        loop = false,
-        orientation = 'vertical',
-        forceMount = false,
-        trailingIcon = 'lucide:chevron-down',
-        ui,
-        class: className,
-        leading,
-        label: labelSlot,
-        trailing,
-        content: contentSlot,
-        body: bodySlot
-    }: Props = $props()
-
-    const variantSlots = $derived(accordionVariants({ disabled }))
-    const rootClass = $derived(
-        variantSlots.root({ class: [config.slots.root, ui?.root, className] })
-    )
-
-    const singleValue = $derived(typeof value === 'string' ? value : undefined)
-    const multipleValue = $derived(Array.isArray(value) ? value : undefined)
-
-    const slotNames = [
-        'item',
-        'header',
-        'trigger',
-        'content',
-        'body',
-        'leadingIcon',
-        'trailingIcon',
-        'label'
-    ] as const
-
-    type SlotName = (typeof slotNames)[number]
-
-    const itemDefaults = $derived.by(() => {
-        const result = {} as Record<SlotName, string>
-        for (const slot of slotNames) {
-            result[slot] = variantSlots[slot]({ class: [config.slots[slot], ui?.[slot]] })
-        }
-        return result
-    })
-
-    function getItemClasses(item: AccordionItem) {
-        if (!item.ui && item.class === undefined && item.disabled === undefined) {
-            return itemDefaults
-        }
-        const result = {} as Record<SlotName, string>
-        for (const slot of slotNames) {
-            const baseClass = [
-                config.slots[slot],
-                ui?.[slot],
-                item.ui?.[slot],
-                slot === 'item' ? item.class : undefined
-            ]
-            const opts =
-                slot === 'trigger'
-                    ? { class: baseClass, disabled: item.disabled }
-                    : { class: baseClass }
-            result[slot] = variantSlots[slot](opts)
-        }
-        return result
-    }
-
-    function isOpen(itemValue: string): boolean {
-        if (!value) return false
-        if (Array.isArray(value)) return value.includes(itemValue)
-        return value === itemValue
-    }
-
-    function handleSingleValueChange(newValue: string) {
-        value = newValue
-        onValueChange?.(newValue)
-    }
-
-    function handleMultipleValueChange(newValue: string[]) {
-        value = newValue
-        onValueChange?.(newValue)
-    }
+<script lang="ts" module></script>
+
+<script lang="ts">import { Accordion } from "bits-ui";
+import { slide } from "svelte/transition";
+import { accordionVariants, accordionDefaults } from "./accordion.variants.js";
+import { getComponentConfig } from "../../config.js";
+import Icon from "../Icon/Icon.svelte";
+const config = getComponentConfig("accordion", accordionDefaults);
+let {
+  items = [],
+  type = "single",
+  value = $bindable(),
+  onValueChange,
+  disabled = false,
+  loop = false,
+  orientation = "vertical",
+  forceMount = false,
+  trailingIcon = "lucide:chevron-down",
+  ui,
+  class: className,
+  leading,
+  label: labelSlot,
+  trailing,
+  content: contentSlot,
+  body: bodySlot
+} = $props();
+const variantSlots = $derived(accordionVariants({ disabled }));
+const rootClass = $derived(
+  variantSlots.root({ class: [config.slots.root, ui?.root, className] })
+);
+const singleValue = $derived(typeof value === "string" ? value : void 0);
+const multipleValue = $derived(Array.isArray(value) ? value : void 0);
+const slotNames = [
+  "item",
+  "header",
+  "trigger",
+  "content",
+  "body",
+  "leadingIcon",
+  "trailingIcon",
+  "label"
+];
+const itemDefaults = $derived.by(() => {
+  const result = {};
+  for (const slot of slotNames) {
+    result[slot] = variantSlots[slot]({ class: [config.slots[slot], ui?.[slot]] });
+  }
+  return result;
+});
+function getItemClasses(item) {
+  if (!item.ui && item.class === void 0 && item.disabled === void 0) {
+    return itemDefaults;
+  }
+  const result = {};
+  for (const slot of slotNames) {
+    const baseClass = [
+      config.slots[slot],
+      ui?.[slot],
+      item.ui?.[slot],
+      slot === "item" ? item.class : void 0
+    ];
+    const opts = slot === "trigger" ? { class: baseClass, disabled: item.disabled } : { class: baseClass };
+    result[slot] = variantSlots[slot](opts);
+  }
+  return result;
+}
+function isOpen(itemValue) {
+  if (!value) return false;
+  if (Array.isArray(value)) return value.includes(itemValue);
+  return value === itemValue;
+}
+function handleSingleValueChange(newValue) {
+  value = newValue;
+  onValueChange?.(newValue);
+}
+function handleMultipleValueChange(newValue) {
+  value = newValue;
+  onValueChange?.(newValue);
+}
 </script>
 
 {#snippet accordionItem(item: AccordionItem, index: number)}

package/dist/components/Alert/Alert.svelte

@@ -0,0 +1,119 @@
+<script lang="ts" module></script>
+
+<script lang="ts">import { alertVariants, alertDefaults } from "./alert.variants.js";
+import { getComponentConfig, iconsDefaults } from "../../config.js";
+import Icon from "../Icon/Icon.svelte";
+import Avatar from "../Avatar/Avatar.svelte";
+import Button from "../Button/Button.svelte";
+const config = getComponentConfig("alert", alertDefaults);
+const icons = getComponentConfig("icons", iconsDefaults);
+let {
+  ref = $bindable(null),
+  as = "div",
+  ui,
+  title,
+  description,
+  icon,
+  avatar,
+  color = config.defaultVariants.color,
+  variant = config.defaultVariants.variant,
+  orientation = config.defaultVariants.orientation,
+  open = $bindable(true),
+  close = false,
+  closeIcon,
+  actions,
+  class: className,
+  leading,
+  titleSlot,
+  descriptionSlot,
+  actionsSlot,
+  closeSlot,
+  onClose,
+  ...restProps
+} = $props();
+const resolvedCloseIcon = $derived(closeIcon ?? icons.close);
+const classes = $derived.by(() => {
+  const slots = alertVariants({ variant, color, orientation, title: !!title });
+  return {
+    root: slots.root({ class: [config.slots.root, className, ui?.root] }),
+    wrapper: slots.wrapper({ class: [config.slots.wrapper, ui?.wrapper] }),
+    title: slots.title({ class: [config.slots.title, ui?.title] }),
+    description: slots.description({ class: [config.slots.description, ui?.description] }),
+    icon: slots.icon({ class: [config.slots.icon, ui?.icon] }),
+    avatar: slots.avatar({ class: [config.slots.avatar, ui?.avatar] }),
+    actions: slots.actions({ class: [config.slots.actions, ui?.actions] }),
+    close: slots.close({ class: [config.slots.close, ui?.close] })
+  };
+});
+const closeButtonProps = $derived(!close ? null : close === true ? {} : close);
+const isVertical = $derived(orientation === "vertical");
+const hasActions = $derived(!!actionsSlot || actions && actions.length > 0);
+function handleClose() {
+  open = false;
+  onClose?.();
+}
+</script>
+
+{#snippet actionsContent()}
+    {#if actionsSlot}
+        {@render actionsSlot()}
+    {:else if actions && actions.length > 0}
+        <div class={classes.actions}>
+            {#each actions as action, index (index)}
+                <Button size="xs" {...action} />
+            {/each}
+        </div>
+    {/if}
+{/snippet}
+
+{#if open}
+    <svelte:element this={as} bind:this={ref} class={classes.root} role="alert" {...restProps}>
+        {#if leading}
+            {@render leading()}
+        {:else if icon}
+            <Icon name={icon} class={classes.icon} />
+        {:else if avatar}
+            <Avatar {...avatar} class={classes.avatar} />
+        {/if}
+
+        {#if title || description || titleSlot || descriptionSlot || (isVertical && hasActions)}
+            <div class={classes.wrapper}>
+                {#if titleSlot}
+                    {@render titleSlot()}
+                {:else if title}
+                    <div class={classes.title}>{title}</div>
+                {/if}
+
+                {#if descriptionSlot}
+                    {@render descriptionSlot()}
+                {:else if description}
+                    <div class={classes.description}>{description}</div>
+                {/if}
+
+                {#if isVertical}
+                    {@render actionsContent()}
+                {/if}
+            </div>
+        {/if}
+
+        {#if !isVertical}
+            {@render actionsContent()}
+        {/if}
+
+        {#if closeSlot}
+            <div class={classes.close}>
+                {@render closeSlot()}
+            </div>
+        {:else if closeButtonProps}
+            <Button
+                {...closeButtonProps}
+                icon={closeButtonProps.icon ?? resolvedCloseIcon}
+                variant={closeButtonProps.variant ?? 'link'}
+                color={closeButtonProps.color ?? 'surface'}
+                class={classes.close}
+                onclick={handleClose}
+                aria-label={closeButtonProps['aria-label'] ?? 'Close alert'}
+            />
+        {/if}
+    </svelte:element>
+{/if}

package/dist/components/Avatar/Avatar.svelte

@@ -0,0 +1,86 @@
+<script lang="ts" module></script>
+
+<script lang="ts">import { Avatar } from "bits-ui";
+import { avatarVariants, avatarDefaults, avatarSizePx } from "./avatar.variants.js";
+import { getComponentConfig } from "../../config.js";
+import { getContext } from "svelte";
+import Icon from "../Icon/Icon.svelte";
+import Chip from "../Chip/Chip.svelte";
+const config = getComponentConfig("avatar", avatarDefaults);
+let {
+  ref = $bindable(null),
+  src,
+  alt,
+  size,
+  rounded,
+  text,
+  icon,
+  chip,
+  loading,
+  delayMs = 0,
+  class: className,
+  ui,
+  fallback: fallbackSnippet,
+  children,
+  ...restProps
+} = $props();
+const groupContext = getContext("avatarGroup");
+const resolvedSize = $derived(size ?? groupContext?.size ?? config.defaultVariants.size ?? "md");
+const resolvedRounded = $derived(
+  rounded ?? groupContext?.rounded ?? config.defaultVariants.rounded ?? "full"
+);
+const sizePx = $derived(avatarSizePx[resolvedSize]);
+const initials = $derived(
+  text !== void 0 ? text : alt ? alt.split(" ").filter(Boolean).slice(0, 2).map((w) => w[0]).join("").toUpperCase() : ""
+);
+const chipProps = $derived(
+  chip === true ? { inset: true } : chip ? { inset: true, ...chip } : void 0
+);
+const classes = $derived.by(() => {
+  const slots = avatarVariants({ size: resolvedSize, rounded: resolvedRounded });
+  return {
+    root: slots.root({
+      class: [config.slots.root, groupContext?.baseClass, className, ui?.root]
+    }),
+    image: slots.image({ class: [config.slots.image, ui?.image] }),
+    fallback: slots.fallback({ class: [config.slots.fallback, ui?.fallback] }),
+    icon: slots.icon({ class: [config.slots.icon, ui?.icon] })
+  };
+});
+</script>
+
+{#snippet avatarContent()}
+    <Avatar.Root {...restProps} bind:ref class={classes.root} {delayMs}>
+        {#if children}
+            {@render children()}
+        {:else}
+            {#if src}
+                <Avatar.Image
+                    {src}
+                    alt={alt ?? ''}
+                    class={classes.image}
+                    width={sizePx}
+                    height={sizePx}
+                    {loading}
+                />
+            {/if}
+            <Avatar.Fallback class={classes.fallback}>
+                {#if fallbackSnippet}
+                    {@render fallbackSnippet()}
+                {:else if initials}
+                    {initials}
+                {:else if icon}
+                    <Icon name={icon} class={classes.icon} />
+                {/if}
+            </Avatar.Fallback>
+        {/if}
+    </Avatar.Root>
+{/snippet}
+
+{#if chipProps}
+    <Chip {...chipProps}>
+        {@render avatarContent()}
+    </Chip>
+{:else}
+    {@render avatarContent()}
+{/if}