@quaffui/quaff 1.0.0-beta1 → 1.0.0-beta13

package/README.md

@@ -11,6 +11,7 @@ This is an independent project and is not endorsed by or affiliated with Materia
 
 Key features:
 
+- Beautiful [documentation](https://quaff.dev/)
 - Built for [Svelte 5](https://svelte.dev/) and [SvelteKit](https://kit.svelte.dev/) with full runes support
 - Follows Material Design 3 guidelines
 - Type-safe components with TypeScript
@@ -62,6 +63,7 @@ You can preview the production build with `bun run preview`.
 - `/src/lib/css` - Styling and theming utilities
 - `/src/routes` - Documentation and examples
 - `/docgen` - Documentation generation tools
+- `/plugins` - Preprocessors used by Quaff (compiled by the relevant package scripts)
 
 ## Acknowledgements
 

package/dist/classes/QScrollObserver.svelte.d.ts

@@ -1,8 +1,6 @@
 type Direction = "up" | "right" | "down" | "left";
-type WindowScrollType = "scrollX" | "scrollY";
 type DocumentScrollType = "scrollLeft" | "scrollTop";
 type ScrollType = {
-    window: WindowScrollType;
     document: DocumentScrollType;
 };
 type Target = HTMLElement | typeof window | Document | string;
@@ -30,6 +28,7 @@ export default class QScrollObserver {
     protected lastScroll: number;
     protected horizontal: boolean;
     protected clearTimer: (() => void) | null;
+    protected removeScrollListener: (() => void) | null;
     protected target: Exclude<Target, string> | null;
     protected debounce: number;
     protected handler: (e: Event) => void;
@@ -40,9 +39,10 @@ export default class QScrollObserver {
     position: number;
     constructor(target?: Target | null, { horizontal, debounce }?: ScrollObserverOptions);
     protected getScrollPosition(target?: HTMLElement | typeof window | undefined): number;
+    protected isScrollEventForTarget(eventTarget: EventTarget | null): boolean;
     protected baseHandler(e: Event): void;
-    protected updateDirection(target: HTMLElement): void;
-    protected handleDebounce(target: HTMLElement, debounce: number): void;
+    protected updateDirection(target: HTMLElement | typeof window): void;
+    protected handleDebounce(target: HTMLElement | typeof window, debounce: number): void;
     destroy(): void;
 }
 export {};

package/dist/classes/QScrollObserver.svelte.js

@@ -1,5 +1,8 @@
 import { onMount } from "svelte";
+import { on } from "svelte/events";
+import { scrollX, scrollY } from "svelte/reactivity/window";
 import { elFromSelector } from "../utils";
+const SCROLL_LISTENER_OPTIONS = { capture: true };
 /**
  * A scroll observer utility.
  * @example
@@ -17,12 +20,12 @@ import { elFromSelector } from "../utils";
  */
 export default class QScrollObserver {
     scrollType = {
-        window: "scrollY",
         document: "scrollTop",
     };
     lastScroll;
     horizontal = false;
     clearTimer = null;
+    removeScrollListener = null;
     target = null;
     debounce = 0;
     handler;
@@ -34,10 +37,8 @@ export default class QScrollObserver {
     constructor(target, { horizontal, debounce } = { horizontal: false, debounce: 0 }) {
         this.horizontal = horizontal ?? false;
         this.debounce = debounce ?? 0;
-        this.handler = this.baseHandler.bind(this);
-        this.scrollType = horizontal
-            ? { window: "scrollX", document: "scrollLeft" }
-            : { window: "scrollY", document: "scrollTop" };
+        this.handler = (e) => this.baseHandler(e);
+        this.scrollType = horizontal ? { document: "scrollLeft" } : { document: "scrollTop" };
         this.lastScroll = 0;
         this.position = 0;
         this.inflectionPoint = 0;
@@ -49,25 +50,36 @@ export default class QScrollObserver {
                 parsedTarget = window;
             }
             this.target = parsedTarget;
-            parsedTarget.addEventListener("scroll", this.handler, { capture: true });
+            this.removeScrollListener = on(parsedTarget, "scroll", this.handler, SCROLL_LISTENER_OPTIONS);
             return this.destroy.bind(this);
         });
     }
     getScrollPosition(target = window) {
         return Math.max(0, target === window
-            ? target[this.scrollType.window]
+            ? ((this.horizontal ? scrollX.current : scrollY.current) ?? 0)
             : target[this.scrollType.document]);
     }
+    isScrollEventForTarget(eventTarget) {
+        if (!this.target || !eventTarget) {
+            return false;
+        }
+        if (this.target === window) {
+            return (eventTarget === document ||
+                eventTarget === document.documentElement ||
+                eventTarget === window);
+        }
+        return eventTarget === this.target;
+    }
     baseHandler(e) {
-        const eventTarget = e.target;
-        if (!eventTarget || !this.target || eventTarget !== this.target) {
+        if (!this.isScrollEventForTarget(e.target)) {
             return;
         }
+        const target = this.target;
         if (this.debounce) {
-            this.handleDebounce(this.target, this.debounce);
+            this.handleDebounce(target, this.debounce);
         }
         else {
-            this.updateDirection(this.target);
+            this.updateDirection(target);
         }
     }
     updateDirection(target) {
@@ -87,7 +99,7 @@ export default class QScrollObserver {
         if (this.clearTimer) {
             return;
         }
-        const timer = setTimeout(this.updateDirection.bind(this, target), debounce);
+        const timer = setTimeout(() => this.updateDirection(target), debounce);
         this.clearTimer = () => {
             clearTimeout(timer);
             this.clearTimer = null;
@@ -96,7 +108,8 @@ export default class QScrollObserver {
     destroy() {
         this.clearTimer?.();
         this.clearTimer = null;
-        this.target?.removeEventListener("scroll", this.handler);
+        this.removeScrollListener?.();
+        this.removeScrollListener = null;
         this.target = null;
         this.direction = "down";
         this.changedDirection = false;

package/dist/classes/Quaff.svelte.d.ts

@@ -1,3 +1,4 @@
+type DisplayMode = "light" | "dark";
 declare class Quaff {
     version: string;
     private static readonly breakpointList;
@@ -15,6 +16,8 @@ declare class Quaff {
     router: import("@sveltejs/kit").Page<Record<string, string>, string | null>;
     protected dark: boolean;
     init(): void;
+    protected getCurrentDisplayMode(): DisplayMode;
+    protected applyDisplayMode(displayMode: DisplayMode, persist?: boolean): void;
     protected toggleDarkMode(): void;
     protected setDarkMode(newVal: boolean): void;
     get darkMode(): {

package/dist/classes/Quaff.svelte.js

@@ -2,6 +2,7 @@ import { onMount } from "svelte";
 import { innerWidth } from "svelte/reactivity/window";
 import { version } from "../helpers";
 import { page } from "$app/state";
+const DISPLAY_MODE_STORAGE_KEY = "displayMode";
 class Quaff {
     version = version;
     static breakpointList = {
@@ -53,28 +54,31 @@ class Quaff {
     dark = $state(false);
     init() {
         onMount(() => {
-            const currentMode = localStorage.getItem("current_mode") ||
-                (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
-            if (currentMode === "dark") {
-                this.dark = true;
-            }
-            else {
-                this.dark = false;
-            }
+            this.applyDisplayMode(this.getCurrentDisplayMode(), false);
         });
     }
+    getCurrentDisplayMode() {
+        const savedDisplayMode = localStorage.getItem(DISPLAY_MODE_STORAGE_KEY);
+        if (savedDisplayMode === "dark" || savedDisplayMode === "light") {
+            return savedDisplayMode;
+        }
+        return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+    applyDisplayMode(displayMode, persist = true) {
+        this.dark = displayMode === "dark";
+        if (typeof document !== "undefined") {
+            document.body.classList.remove("body--light", "body--dark");
+            document.body.classList.add(`body--${displayMode}`);
+        }
+        if (persist && typeof localStorage !== "undefined") {
+            localStorage.setItem(DISPLAY_MODE_STORAGE_KEY, displayMode);
+        }
+    }
     toggleDarkMode() {
-        this.dark = !this.dark;
-        const mode = {
-            from: this.dark ? "light" : "dark",
-            to: this.dark ? "dark" : "light",
-        };
-        const body = document.querySelector("body");
-        body?.classList.replace(`body--${mode.from}`, `body--${mode.to}`);
-        localStorage.setItem("current_mode", mode.to);
+        this.applyDisplayMode(this.dark ? "light" : "dark");
     }
     setDarkMode(newVal) {
-        this.dark = newVal;
+        this.applyDisplayMode(newVal ? "dark" : "light");
     }
     get darkMode() {
         // eslint-disable-next-line @typescript-eslint/no-this-alias

package/dist/components/avatar/QAvatar.svelte

@@ -2,6 +2,7 @@
   import { useSize } from "../../composables";
   import type { QAvatarProps } from "./props";
 
+  // #region:    --- Props
   let {
     alt,
     shape = "circle",
@@ -13,9 +14,12 @@
     videoAccessibility,
     ...props
   }: QAvatarProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Derived values
   const qSize = $derived(useSize(size, "q-avatar"));
   const qShape = $derived(`q-avatar--${shape}`);
+  // #endregion: --- Derived values
 </script>
 
 <div

package/dist/components/avatar/QAvatar.svelte.d.ts

@@ -1,14 +1,4 @@
-import { SvelteComponentTyped } from "svelte";
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-};
-type QAvatarProps_ = typeof __propDef.props;
-export { QAvatarProps_ as QAvatarProps };
-export type QAvatarEvents = typeof __propDef.events;
-export type QAvatarSlots = typeof __propDef.slots;
-export default class QAvatar extends SvelteComponentTyped<QAvatarProps_, QAvatarEvents, QAvatarSlots> {
-}
+import type { QAvatarProps } from "./props";
+declare const QAvatar: import("svelte").Component<QAvatarProps, {}, "">;
+type QAvatar = ReturnType<typeof QAvatar>;
+export default QAvatar;

package/dist/components/breadcrumbs/QBreadcrumbs.scss

@@ -1,10 +1,14 @@
 .q-breadcrumbs {
-  display: flex;
-  align-items: center;
-  justify-content: center;
   width: fit-content;
 
-  & > .q-breadcrumbs__separator:first-child {
-    display: none;
+  &__list {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    margin: 0;
+    padding: 0;
+
+    list-style: none;
   }
 }

package/dist/components/breadcrumbs/QBreadcrumbs.svelte

@@ -1,36 +1,66 @@
-<script lang="ts">
-  import { setContext, untrack } from "svelte";
-  import { QBreadcrumbsCtxName } from "../../utils";
+<script lang="ts" module>
   import type { QBreadcrumbsProps } from "./props";
 
+  export const breadcrumbsCtx = QContext<{
+    readonly separator: QBreadcrumbsProps["separator"];
+    readonly gutter: QBreadcrumbsProps["gutter"];
+  }>("QBreadcrumbs");
+</script>
+
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { QContext } from "../../utils";
+  import { useColor } from "../../composables";
+
+  // #region:    --- Props
   let {
     activeColor = "primary",
     gutter = "sm",
     separator = "/",
-    separatorColor = "outline",
+    separatorColor = "outline-variant",
     children,
     ...props
   }: QBreadcrumbsProps = $props();
+  // #endregion: --- Props
+
+  // #region:    --- Derived values
+  const parsedActiveColor = $derived(useColor(activeColor));
+  const parsedSeparatorColor = $derived(useColor(separatorColor));
+  // #endregion: --- Derived values
 
-  let breadrumbElement: HTMLDivElement;
+  // #region:    --- Non-reactive variables
+  let breadcrumbList: HTMLOListElement;
+  // #endregion: --- Non-reactive variables
 
-  $effect(() => {
-    untrack(() => breadrumbElement.firstChild?.remove());
+  // #region:    --- Context
+  breadcrumbsCtx.set({
+    get separator() {
+      return separator;
+    },
+    get gutter() {
+      return gutter;
+    },
   });
+  // #endregion: --- Context
 
-  setContext(QBreadcrumbsCtxName.activeColor, activeColor);
-  setContext(QBreadcrumbsCtxName.separator, {
-    type: separator,
-    color: separatorColor,
-    gutter,
+  // #region:    --- Lifecycle
+  onMount(() => {
+    breadcrumbList
+      .querySelector(".q-breadcrumbs__separator:first-child")
+      ?.remove();
   });
+  // #endregion: --- Lifecycle
 </script>
 
-<div
-  bind:this={breadrumbElement}
+<nav
   {...props}
   class={["q-breadcrumbs", props.class]}
+  aria-label="Breadcrumbs"
   data-quaff
+  style:--q-separator-color={parsedSeparatorColor}
+  style:--q-active-color={parsedActiveColor}
 >
-  {@render children?.()}
-</div>
+  <ol bind:this={breadcrumbList} class="q-breadcrumbs__list">
+    {@render children?.()}
+  </ol>
+</nav>

package/dist/components/breadcrumbs/QBreadcrumbs.svelte.d.ts

@@ -1,14 +1,26 @@
-import { SvelteComponentTyped } from "svelte";
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
+import type { QBreadcrumbsProps } from "./props";
+export declare const breadcrumbsCtx: {
+    readonly symbol: symbol;
+    get(): {
+        readonly separator: QBreadcrumbsProps["separator"];
+        readonly gutter: QBreadcrumbsProps["gutter"];
+    } | undefined;
+    assertGet(errorMsg?: string): {
+        readonly separator: QBreadcrumbsProps["separator"];
+        readonly gutter: QBreadcrumbsProps["gutter"];
     };
-    slots: {};
+    set(context: {
+        readonly separator: QBreadcrumbsProps["separator"];
+        readonly gutter: QBreadcrumbsProps["gutter"];
+    }): void;
+    reset(): void;
+    exists(): boolean;
+    updateEntry(key: "separator" | "gutter", value: any): void;
+    updateEntries(updates: Partial<{
+        readonly separator: QBreadcrumbsProps["separator"];
+        readonly gutter: QBreadcrumbsProps["gutter"];
+    }>): void;
 };
-type QBreadcrumbsProps_ = typeof __propDef.props;
-export { QBreadcrumbsProps_ as QBreadcrumbsProps };
-export type QBreadcrumbsEvents = typeof __propDef.events;
-export type QBreadcrumbsSlots = typeof __propDef.slots;
-export default class QBreadcrumbs extends SvelteComponentTyped<QBreadcrumbsProps_, QBreadcrumbsEvents, QBreadcrumbsSlots> {
-}
+declare const QBreadcrumbs: import("svelte").Component<QBreadcrumbsProps, {}, "">;
+type QBreadcrumbs = ReturnType<typeof QBreadcrumbs>;
+export default QBreadcrumbs;

package/dist/components/breadcrumbs/QBreadcrumbsEl.scss

@@ -1,10 +1,29 @@
 @use "$css/mixins";
 
-.q-breadcrumbs__el {
+.q-breadcrumbs__item {
   display: flex;
   align-items: center;
 
-  & > .q-icon {
-    @include mixins.margin("r-sm");
+  color: var(--q-breadcrumbs-color, currentColor);
+
+  &:has(> a):hover .q-breadcrumbs__label {
+    text-decoration: underline;
+    text-decoration-color: currentColor;
+
+    &__item:first-child > .q-breadcrumbs__separator {
+      display: none;
+    }
+  }
+
+  .q-breadcrumbs__separator {
+    color: var(--q-separator-color, currentColor);
+  }
+
+  .q-breadcrumbs__el {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    text-decoration: none;
+    color: inherit;
   }
 }

package/dist/components/breadcrumbs/QBreadcrumbsEl.svelte

@@ -1,33 +1,30 @@
 <script lang="ts">
-  import { getContext, type Snippet } from "svelte";
   import { QIcon } from "../..";
-  import { isRouteActive, QBreadcrumbsCtxName } from "../../utils";
+  import { isRouteActive } from "../../utils";
+  import { breadcrumbsCtx } from "./QBreadcrumbs.svelte";
   import type { MaterialSymbol } from "material-symbols";
   import type { QBreadcrumbsElProps } from "./props";
 
+  // #region:    --- Props
   let {
     activeClass = "active",
     href,
     label = "",
     icon,
-    tag = "div",
+    tag = "span",
     to,
     children = fallback,
     ...props
   }: QBreadcrumbsElProps = $props();
+  // #endregion: --- Props
 
-  const activeColor = getContext<string>(QBreadcrumbsCtxName.activeColor);
-  const separator = getContext<{
-    type: `icon:${MaterialSymbol}` | Snippet;
-    color: string;
-    gutter: string;
-  }>(QBreadcrumbsCtxName.separator);
+  // #region:    --- Derived values
+  const isActive = $derived(isRouteActive(href || to));
+  // #endregion: --- Derived values
 
-  const classesIfActive = $derived(
-    isRouteActive(href || to)
-      ? `${activeClass} text-${activeColor}`
-      : undefined,
-  );
+  // #region:    --- Context
+  const ctx = breadcrumbsCtx.assertGet();
+  // #endregion: --- Context
 </script>
 
 {#snippet fallback()}
@@ -39,38 +36,53 @@
     {#if typeof icon === "string"}
       <QIcon name={icon} size="1rem" />
     {:else}
-      {@render icon()}
+      <span class="q-icon">
+        {@render icon()}
+      </span>
     {/if}
   {/if}
 
-  {@render children()}
+  <span class="q-breadcrumbs__label">
+    {@render children()}
+  </span>
 {/snippet}
 
-<div
+<li
   {...props}
-  class={["q-breadcrumbs__separator", `q-px-${separator.gutter}`, props.class]}
-  data-quaff
+  class={["q-breadcrumbs__item", props.class]}
+  style:--q-breadcrumbs-color={isActive ? "var(--q-active-color)" : undefined}
 >
-  {#if typeof separator.type === "string"}
-    {#if separator.type.startsWith("icon:")}
-      <QIcon
-        name={separator.type.replace("icon:", "") as MaterialSymbol}
-        size="1rem"
-      />
+  <span
+    class={["q-breadcrumbs__separator", `q-px-${ctx?.gutter}`]}
+    aria-hidden="true"
+  >
+    {#if typeof ctx.separator === "string"}
+      {#if ctx.separator.startsWith("icon:")}
+        <QIcon name={ctx.separator.slice(5) as MaterialSymbol} size="1rem" />
+      {:else}
+        {ctx.separator}
+      {/if}
     {:else}
-      {separator.type}
+      {@render ctx.separator?.()}
     {/if}
+  </span>
+
+  {#if href || to}
+    <a
+      href={href || to}
+      class={["q-breadcrumbs__el", isActive && activeClass]}
+      aria-current={isActive ? "page" : undefined}
+      data-quaff
+    >
+      {@render breadcrumbEl()}
+    </a>
   {:else}
-    {@render separator.type()}
+    <svelte:element
+      this={tag}
+      class={["q-breadcrumbs__el", isActive && activeClass]}
+      data-quaff
+    >
+      {@render breadcrumbEl()}
+    </svelte:element>
   {/if}
-</div>
-
-{#if href !== undefined || to !== undefined}
-  <a href={href || to} class={["q-breadcrumbs__el", classesIfActive]}>
-    {@render breadcrumbEl()}
-  </a>
-{:else}
-  <svelte:element this={tag} class={["q-breadcrumbs__el", classesIfActive]}>
-    {@render breadcrumbEl()}
-  </svelte:element>
-{/if}
+</li>

package/dist/components/breadcrumbs/QBreadcrumbsEl.svelte.d.ts

@@ -1,14 +1,4 @@
-import { SvelteComponentTyped } from "svelte";
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-};
-type QBreadcrumbsElProps_ = typeof __propDef.props;
-export { QBreadcrumbsElProps_ as QBreadcrumbsElProps };
-export type QBreadcrumbsElEvents = typeof __propDef.events;
-export type QBreadcrumbsElSlots = typeof __propDef.slots;
-export default class QBreadcrumbsEl extends SvelteComponentTyped<QBreadcrumbsElProps_, QBreadcrumbsElEvents, QBreadcrumbsElSlots> {
-}
+import type { QBreadcrumbsElProps } from "./props";
+declare const QBreadcrumbsEl: import("svelte").Component<QBreadcrumbsElProps, {}, "">;
+type QBreadcrumbsEl = ReturnType<typeof QBreadcrumbsEl>;
+export default QBreadcrumbsEl;

package/dist/components/breadcrumbs/props.d.ts

@@ -2,7 +2,7 @@ import type { MaterialSymbol } from "material-symbols";
 import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
 export type QBreadcrumbsGutterOptions = Exclude<Q.Size, "xs" | "xl">;
-export interface QBreadcrumbsProps extends HTMLAttributes<HTMLDivElement> {
+export interface QBreadcrumbsProps extends HTMLAttributes<HTMLElement> {
     /**
      * Color to use for the active breadcrumb element. See <link to colors docs> to see what colors can be used.
      * @default "primary"
@@ -17,14 +17,14 @@ export interface QBreadcrumbsProps extends HTMLAttributes<HTMLDivElement> {
      * Separator to use between the breadcrumb elements. To use an icon, prefix with "icon:" followed by the name of the icon.
      * @default "/"
      */
-    separator?: string | `icon:${MaterialSymbol}` | Snippet;
+    separator?: Q.StringWithSuggestions<`icon:${MaterialSymbol}`> | Snippet;
     /**
      * Color to use for the separators. See <link to colors docs> to see what colors can be used.
      * @default "outline"
      */
     separatorColor?: string;
 }
-export interface QBreadcrumbsElProps extends HTMLAttributes<HTMLElement> {
+export interface QBreadcrumbsElProps extends HTMLAttributes<HTMLLIElement> {
     /**
      * Class to apply to the breadcrumb element when the route is active.
      * @default "active"
@@ -47,7 +47,7 @@ export interface QBreadcrumbsElProps extends HTMLAttributes<HTMLElement> {
     href?: string;
     /**
      * Tag to use for the breadcrumb element.
-     * @default "div"
+     * @default "span"
      */
     tag?: string;
     /**

package/dist/components/button/QBtn.scss

@@ -34,6 +34,8 @@
       variables.$speed3 border-radius,
       variables.$speed3 padding;
 
+    isolation: isolate;
+
     @include mixins.btn-image;
 
     $sizeMap: (
@@ -96,7 +98,7 @@
     }
 
     &--outlined {
-      outline: solid 0.0625rem var(--outline);
+      outline: solid 0.0625rem var(--outline-variant);
 
       &:not([aria-disabled]):focus {
         outline-color: var(--primary);