@quaffui/quaff 1.0.0-beta7 → 1.0.0-beta9

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 (in development, don't forget to run `bun gen:plugins` before `bun dev`)
 
 ## Acknowledgements
 

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

@@ -12,7 +12,7 @@ declare class Quaff {
         lg: number;
         xl: number;
     };
-    router: import("@sveltejs/kit").Page<import("../../..").LayoutParams<"/">, import("../../..").RouteId | null>;
+    router: import("@sveltejs/kit").Page<Record<string, string>, string | null>;
     protected dark: boolean;
     init(): void;
     protected toggleDarkMode(): void;

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/breadcrumbs/QBreadcrumbs.svelte

@@ -1,8 +1,17 @@
-<script lang="ts">
-  import { onMount, setContext } 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";
+
+  // #region:    --- Props
   let {
     activeColor = "primary",
     gutter = "sm",
@@ -11,16 +20,30 @@
     children,
     ...props
   }: QBreadcrumbsProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Non-reactive variables
   let breadcrumbList: HTMLOListElement;
+  // #endregion: --- Non-reactive variables
+
+  // #region:    --- Context
+  breadcrumbsCtx.set({
+    get separator() {
+      return separator;
+    },
+    get gutter() {
+      return gutter;
+    },
+  });
+  // #endregion: --- Context
 
+  // #region:    --- Lifecycle
   onMount(() => {
     breadcrumbList
       .querySelector(".q-breadcrumbs__separator:first-child")
       ?.remove();
   });
-
-  setContext(QBreadcrumbsCtxName.separator, { type: separator, gutter });
+  // #endregion: --- Lifecycle
 </script>
 
 <nav

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

@@ -1,4 +1,27 @@
 import { SvelteComponentTyped } from "svelte";
+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"];
+    };
+    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;
+};
 declare const __propDef: {
     props: Record<string, never>;
     events: {

package/dist/components/breadcrumbs/QBreadcrumbsEl.svelte

@@ -1,10 +1,11 @@
 <script lang="ts">
-  import { getContext } 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, QBreadcrumbsProps } from "./props";
+  import type { QBreadcrumbsElProps } from "./props";
 
+  // #region:    --- Props
   let {
     activeClass = "active",
     href,
@@ -15,13 +16,15 @@
     children = fallback,
     ...props
   }: QBreadcrumbsElProps = $props();
+  // #endregion: --- Props
 
-  const separator = getContext<{
-    type: QBreadcrumbsProps["separator"];
-    gutter: QBreadcrumbsProps["gutter"];
-  }>(QBreadcrumbsCtxName.separator);
-
+  // #region:    --- Derived values
   const isActive = $derived(isRouteActive(href || to));
+  // #endregion: --- Derived values
+
+  // #region:    --- Context
+  const ctx = breadcrumbsCtx.assertGet();
+  // #endregion: --- Context
 </script>
 
 {#snippet fallback()}
@@ -50,17 +53,17 @@
   style:--q-breadcrumbs-color={isActive ? "var(--q-active-color)" : undefined}
 >
   <span
-    class={["q-breadcrumbs__separator", `q-px-${separator.gutter}`]}
+    class={["q-breadcrumbs__separator", `q-px-${ctx?.gutter}`]}
     aria-hidden="true"
   >
-    {#if typeof separator.type === "string"}
-      {#if separator.type.startsWith("icon:")}
-        <QIcon name={separator.type.slice(5) as MaterialSymbol} size="1rem" />
+    {#if typeof ctx.separator === "string"}
+      {#if ctx.separator.startsWith("icon:")}
+        <QIcon name={ctx.separator.slice(5) as MaterialSymbol} size="1rem" />
       {:else}
-        {separator.type}
+        {ctx.separator}
       {/if}
     {:else}
-      {@render separator.type?.()}
+      {@render ctx.separator?.()}
     {/if}
   </span>
 

package/dist/components/button/QBtn.svelte

@@ -7,6 +7,9 @@
   import type { MaterialSymbol } from "material-symbols";
   import type { QBtnProps, QBtnVariantOptions } from "./props";
 
+  type QBtnMouseEvent = QEvent<MouseEvent, typeof qBtn>;
+
+  // #region:    --- Props
   let {
     disabled = false,
     variant,
@@ -31,12 +34,14 @@
     children,
     ...props
   }: QBtnProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Non-reactive variables
   let qBtn: HTMLElement;
   let qBtnLabel: HTMLSpanElement;
+  // #endregion: --- Non-reactive variables
 
-  type QBtnMouseEvent = QEvent<MouseEvent, typeof qBtn>;
-
+  // #region:    --- Derived values
   const computedTag = $derived(to ? "a" : tag || "button");
   const qSize = $derived(useSize(size, "q-btn"));
 
@@ -84,7 +89,20 @@
   const rippleColorVar = $derived(
     rippleColor ? `var(--${rippleColor}, ${rippleColor})` : colorVar,
   );
+  // #endregion: --- Derived values
+
+  // #region:    --- Lifecycle
+  onMount(() => {
+    const { width, height } = qBtnLabel.getBoundingClientRect();
+
+    // This is required for buttons with no label and with a tooltip to be round
+    if (width === 0 && height === 0) {
+      qBtn.classList.add("q-btn--round");
+    }
+  });
+  // #endregion: --- Lifecycle
 
+  // #region:    --- Functions
   function stopIfDisabled(e: QBtnMouseEvent) {
     if (disabled) {
       e.preventDefault();
@@ -112,15 +130,7 @@
     }) as QBtnMouseEvent;
     stopIfDisabled(click);
   }
-
-  onMount(() => {
-    const { width, height } = qBtnLabel.getBoundingClientRect();
-
-    // This is required for buttons with no label and with a tooltip to be round
-    if (width === 0 && height === 0) {
-      qBtn.classList.add("q-btn--round");
-    }
-  });
+  // #endregion: --- Functions
 </script>
 
 <svelte:element

package/dist/components/card/QCard.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
-  import type { QCardProps } from "./props";
+  import type { QCardProps, QCardFillColors } from "./props";
 
+  // #region:    --- Props
   let {
     fill = false,
     flat = false,
@@ -9,24 +10,27 @@
     children,
     ...props
   }: QCardProps = $props();
+  // #endregion: --- Props
 
-  type ColorOptions = "primary" | "secondary" | "tertiary";
-
-  const colorOptions: ColorOptions[] = [
+  // #region:    --- Non-reactive variables
+  const colorOptions: QCardFillColors[] = [
     "primary",
     "secondary",
     "tertiary",
   ] as const;
+  // #endregion: --- Non-reactive variables
 
+  // #region:    --- Derived values
   const color = $derived.by(() => {
     if (fill) {
-      return fill === true || !colorOptions.includes(fill as ColorOptions)
+      return fill === true || !colorOptions.includes(fill as QCardFillColors)
         ? "surface-variant"
         : fill;
     }
 
     return "surface";
   });
+  // #endregion: --- Derived values
 </script>
 
 <article

package/dist/components/card/QCardActions.svelte

@@ -2,14 +2,18 @@
   import { useAlign } from "../../composables";
   import type { QCardActionsProps } from "./props";
 
+  // #region:    --- Props
   let {
     align,
     vertical = false,
     children,
     ...props
   }: QCardActionsProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Derived values
   const alignClass = $derived(useAlign(align));
+  // #endregion: --- Derived values
 </script>
 
 <nav

package/dist/components/card/QCardSection.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import type { QCardSectionProps } from "./props";
 
+  // #region:    --- Props
   let { horizontal = false, children, ...props }: QCardSectionProps = $props();
+  // #endregion: --- Props
 </script>
 
 <div

package/dist/components/checkbox/QCheckbox.svelte

@@ -1,12 +1,14 @@
 <script lang="ts">
   import type { QCheckboxProps } from "./props";
 
+  // #region:    --- Props
   let {
     value = $bindable(),
     label = "",
     disable = false,
     ...props
   }: QCheckboxProps = $props();
+  // #endregion: --- Props
 </script>
 
 <label

package/dist/components/chip/QChip.svelte

@@ -7,23 +7,43 @@
 
   type QChipMouseEvent = QEvent<MouseEvent, HTMLElement>;
 
+  // #region:    --- Props
   let {
     kind = "assist",
+    selected = $bindable(kind === "filter" ? false : undefined),
     label,
     icon,
     trailingIcon,
     disabled = false,
     elevated,
     noRipple = false,
-    selected = $bindable(kind === "filter" ? false : undefined),
     size = "sm",
     onTrailingIconClick,
     children,
     ...props
   }: QChipProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Non-reactive variables
   let qChip: HTMLDivElement;
+  // #endregion: --- Non-reactive variables
+
+  // #region:    --- Derived values
+  const trailing = $derived(
+    (kind === "assist" || kind === "suggestion") && trailingIcon
+      ? undefined
+      : trailingIcon,
+  );
+
+  const tabindex = disabled ? -1 : props.tabindex || 0;
+  const role = $derived(
+    ["assist", "filter"].includes(kind) ? "button" : undefined,
+  );
+
+  const avatar = $derived(extractImgSrc(icon));
+  // #endregion: --- Derived values
 
+  // #region:    --- Effects
   $effect.pre(() => {
     if (selected !== undefined && kind !== "filter") {
       throw new Error(
@@ -37,20 +57,9 @@
       );
     }
   });
+  // #endregion: --- Effects
 
-  const trailing = $derived(
-    (kind === "assist" || kind === "suggestion") && trailingIcon
-      ? undefined
-      : trailingIcon,
-  );
-
-  const tabindex = disabled ? -1 : props.tabindex || 0;
-  const role = $derived(
-    ["assist", "filter"].includes(kind) ? "button" : undefined,
-  );
-
-  const avatar = $derived(extractImgSrc(icon));
-
+  // #region:    --- Functions
   function stopIfDisabled(e: QChipMouseEvent, iconClick = false) {
     if (disabled) {
       e.preventDefault();
@@ -87,6 +96,7 @@
     }) as QChipMouseEvent;
     stopIfDisabled(click);
   }
+  // #endregion: --- Functions
 </script>
 
 <div

package/dist/components/codeBlock/QCodeBlock.svelte

@@ -3,6 +3,7 @@
   import { copy } from "../../utils";
   import type { QCodeBlockProps } from "./props";
 
+  // #region:    --- Props
   let {
     language,
     lightTheme = "github-light-default",
@@ -12,12 +13,16 @@
     copiable,
     ...props
   }: QCodeBlockProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Reactive variables
   let btnContent = $state("Copy");
   let btnColor = $state("primary");
 
   let html = $state("");
+  // #endregion: --- Reactive variables
 
+  // #region:    --- Effects
   $effect(() => {
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
     Quaff.darkMode.isActive;
@@ -25,7 +30,9 @@
     // This is required to have the html updated when the code changes
     getHtml(code);
   });
+  // #endregion: --- Effects
 
+  // #region:    --- Functions
   function setBtn(type: "base" | "error" | "success") {
     switch (type) {
       case "error":
@@ -68,6 +75,7 @@
       html = `<pre>${code}</pre>`;
     }
   }
+  // #endregion: --- Functions
 </script>
 
 <div {...props} class="q-code-block" data-quaff>

package/dist/components/dialog/QDialog.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import type { QDialogProps } from "./props";
 
+  // #region:    --- Props
   let {
     value = $bindable(false),
     position = "default",
@@ -10,11 +11,17 @@
     children,
     ...props
   }: QDialogProps = $props();
+  // #endregion: --- Props
 
+  // #region:    --- Reactive variables
   let dialogEl = $state<HTMLDialogElement>();
+  // #endregion: --- Reactive variables
 
+  // #region:    --- Derived values
   const canHide = $derived(value && !persistent);
+  // #endregion: --- Derived values
 
+  // #region:    --- Effects
   $effect(() => {
     if (value) {
       dialogEl?.[modal ? "showModal" : "show"]();
@@ -28,7 +35,9 @@
       window.removeEventListener("click", tryCancel);
     }
   });
+  // #endregion: --- Effects
 
+  // #region:    --- Methods
   export function hide() {
     if (dialogEl?.open) {
       value = false;
@@ -48,7 +57,9 @@
       show();
     }
   }
+  // #endregion: --- Methods
 
+  // #region:    --- Functions
   function addAnimation() {
     if (persistent && value) {
       dialogEl?.classList.add("q-dialog--animating");
@@ -77,6 +88,7 @@
       e.preventDefault();
     }
   }
+  // #endregion: --- Functions
 </script>
 
 <dialog

package/dist/components/drawer/QDrawer.svelte

@@ -1,14 +1,11 @@
 <script lang="ts">
-  import { getContext, onMount, untrack } from "svelte";
+  import { onMount, untrack } from "svelte";
   import { on } from "svelte/events";
   import { navigating } from "$app/state";
   import { useSize } from "../../composables";
-  import { QContext } from "../../classes/QContext.svelte";
-  import { QLayoutCtxName } from "../../utils";
-  import type { QLayoutProps } from "../layout/props";
-  import type { DrawerContext } from "../layout/QLayout.svelte";
-  import type { QDrawerProps } from "./props";
+  import { leftDrawerCtx, rightDrawerCtx } from "../layout/QLayout.svelte";
 
+  // #region:    --- Props
   let {
     value = $bindable(false),
     side = "left",
@@ -21,7 +18,10 @@
     children,
     ...props
   }: QDrawerProps = $props();
+  // #endregion: --- Props
+  import type { QDrawerProps } from "./props";
 
+  // #region:    --- Non-reactive variables
   const PEEK_THRESHOLD = 30; // How far the drawer peeks out when cursor is near the edge
   const TRANSITION = "top 0.3s, bottom 0.3s, transform 0.3s";
 
@@ -30,20 +30,22 @@
   let unlistenPointermove: () => void;
   let unlistenPointerup: () => void;
   let unlistenPointercancel: () => void;
+  // #endregion: --- Non-reactive variables
 
+  // #region:    --- Reactive variables
   let drawerEl = $state<HTMLDivElement>();
   let swipeAreaEl = $state<HTMLDivElement>();
 
   let isSwiping = $state(false);
   let startX = $state(0);
   let dragOffset = $state(0);
+  // #endregion: --- Reactive variables
 
-  const drawerContext = QContext.get<DrawerContext>(
-    QLayoutCtxName.drawer[side],
-  );
-  const layoutView = getContext<{ value: NonNullable<QLayoutProps["view"]> }>(
-    QLayoutCtxName.view,
+  // #region:    --- Derived values
+  const drawerCtxToUse = $derived(
+    side === "left" ? leftDrawerCtx : rightDrawerCtx,
   );
+  const drawerContext = $derived(drawerCtxToUse.get());
 
   const canHideOnClickOutside = $derived((value && !persistent) || overlay);
 
@@ -51,31 +53,23 @@
 
   const offsetTop = $derived.by(() => {
     const charPos = side === "left" ? 0 : 2;
-    return layoutView?.value.charAt(charPos) === "h";
+    return drawerContext?.view.charAt(charPos) === "h";
   });
   const offsetBottom = $derived.by(() => {
     const charPos = side === "left" ? 8 : 10;
-    return layoutView?.value.charAt(charPos) === "f";
+    return drawerContext?.view.charAt(charPos) === "f";
   });
 
-  export const show = (e?: MouseEvent) => {
-    if (!value) {
-      value = true;
-      e?.stopPropagation();
-    }
-  };
+  const widthStyle = $derived(!drawerContext ? useSize(width).style : null);
 
-  export const hide = () => {
-    if (value) {
-      value = false;
-    }
-  };
+  const drawerWidthStyle = $derived(
+    widthStyle === null ? "" : `--${side}-drawer-width: ${widthStyle};`,
+  );
 
-  export const toggle = (e?: MouseEvent) => {
-    value = !value;
-    e?.stopPropagation();
-  };
+  const style = $derived(`${drawerWidthStyle}${props.style ?? ""}`);
+  // #endregion: --- Derived values
 
+  // #region:    --- Lifecycle
   onMount(() => {
     setTimeout(() => {
       drawerEl?.style.setProperty("transition", TRANSITION);
@@ -93,14 +87,16 @@
         resetBodyStyles();
       }
 
-      drawerContext?.updateEntries({
-        width: 0,
+      drawerCtxToUse.updateEntries({
         takesSpace: false,
+        width: 0,
         ready: false,
       });
     };
   });
+  // #endregion: --- Lifecycle
 
+  // #region:    --- Effects
   $effect(() => {
     if (navigating.type && hideOnRouteChange) {
       hide();
@@ -137,23 +133,37 @@
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
     [value, overlay, width];
 
-    untrack(() =>
-      drawerContext?.updateEntries({
+    untrack(() => {
+      drawerCtxToUse.updateEntries({
         takesSpace: !!value && !overlay,
         width,
         ready: true,
-      }),
-    );
+      });
+    });
   });
+  // #endregion: --- Effects
 
-  const widthStyle = $derived(!drawerContext ? useSize(width).style : null);
+  // #region:    --- Methods
+  export const show = (e?: MouseEvent) => {
+    if (!value) {
+      value = true;
+      e?.stopPropagation();
+    }
+  };
 
-  const drawerWidthStyle = $derived(
-    widthStyle === null ? "" : `--${side}-drawer-width: ${widthStyle};`,
-  );
+  export const hide = () => {
+    if (value) {
+      value = false;
+    }
+  };
 
-  const style = $derived(`${drawerWidthStyle}${props.style ?? ""}`);
+  export const toggle = (e?: MouseEvent) => {
+    value = !value;
+    e?.stopPropagation();
+  };
+  // #endregion: --- Methods
 
+  // #region:    --- Functions
   function tryClose(e: MouseEvent) {
     const isTargetDrawer = e.target === drawerEl;
     const isTargetInsideDrawer = drawerEl?.contains(e.target as Node);
@@ -315,6 +325,7 @@
     document.body.style.removeProperty("cursor");
     document.body.style.removeProperty("user-select");
   }
+  // #endregion: --- Functions
 </script>
 
 <div