@quaffui/quaff 0.1.0-prealpha9 → 1.0.0-alpha2

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright © 2023 Rubatissimo
+Copyright © 2025 QuaffUI
 
 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:
 

package/README.md

@@ -1,43 +1,76 @@
 # Quaff
 
-Quaff is an experimental project utilizing [Beer CSS](https://www.beercss.com/) and parts of [Quasar Framework](https://quasar.dev/) as the base for Svelte components. This independent project is not endorsed by or affiliated with Beer CSS or Quasar Framework.
+Quaff is a component library for Svelte that follows the [Material Design 3](https://m3.material.io/) guidelines. It provides a comprehensive set of UI components designed to create beautiful, consistent, and accessible web applications.
 
-**This is merely a playground right now, don't expect anything usable!**
+> **⚠️ Early Development Notice:** Quaff is still maturing and not battle-tested yet. Use it in production if you're feeling brave! We welcome contributions and feedback to help shape the library.
+
+## Overview
+
+Quaff is project that draws some inspiration from [Quasar Framework](https://quasar.dev/), [Material Web](https://material-web.dev/) and [BeerCSS](https://www.beercss.com/) adapted specifically for Svelte 5. It implements Material Design 3 (Material You) principles while providing a developer-friendly API.
+This is an independent project and is not endorsed by or affiliated with Material Design 3 or Quasar Framework.
+
+Key features:
+
+- 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
+- Comprehensive component documentation
+- Components auto-import out of the box
+
+## Getting started
+
+Quaff comes with a CLI tool called `create-quaff`. You can use it to easily create a new Quaff project:
+
+```bash
+bun create quaff@latest
+```
 
 ## Developing
 
-Once you've installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+Once you've installed dependencies with `bun install`, start a development server:
 
 ```bash
-npm run dev
+bun run dev
 
 # or start the server and open the app in a new browser tab
-npm run dev -- --open
+bun run open
 ```
 
-Everything inside `src/lib` is part of the library, everything inside `src/routes` can be used as a showcase or preview app.
+Everything inside `src/lib` is part of the library, everything inside `src/routes` serves as documentation and component showcase.
 
 ## Building
 
 To build the library:
 
 ```bash
-npm run package
+bun run package
 ```
 
-To create a production version of your showcase app:
+To create a production version of your app:
 
 ```bash
-npm run build
+bun run build
 ```
 
-You can preview the production build with `npm run preview`.
+You can preview the production build with `bun run preview`.
+
+> To deploy the documentation site, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
 
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
+## Project Structure
 
-## Third-party Libraries
+- `/src/lib/components` - The individual UI components
+- `/src/lib/css` - Styling and theming utilities
+- `/src/routes` - Documentation and examples
+- `/docgen` - Documentation generation tools
 
-This project makes use of the following open source libraries:
+## Acknowledgements
+
+This project draws inspiration from:
 
-- [Beer CSS](https://www.beercss.com/): Copyright (c) 2021 Beer css!. Licensed under the [MIT License](https://github.com/beercss/beercss/blob/main/LICENSE)
 - [Quasar Framework](https://quasar.dev/): Copyright (c) 2015-present Razvan Stoenescu. Licensed under the [MIT License](https://github.com/quasarframework/quasar/blob/dev/LICENSE)
+- [Material Web Components](https://github.com/material-components/material-web): Copyright (c) Google LLC. Licensed under the [Apache License 2.0 License](https://github.com/material-components/material-web/blob/main/LICENSE)
+- [BeerCSS](https://www.beercss.com/): Copyright (c) 2021 Beer css! Licensed under the [MIT License](https://github.com/beercss/beercss/blob/main/LICENSE)
+
+## License
+
+MIT

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

@@ -0,0 +1,42 @@
+/**
+ * This class allows to manipulate reactive contexts more easily.
+ * It avoids having to pass a Svelte store down the components but rather use runes to keep the context reactive.
+ *
+ * This class should be used when the context has to be modified from a child component. Otherwise, using svelte's context API should be enough.
+ */
+export declare class QContext<T> {
+    #private;
+    constructor(contextSymbol: symbol, init: T);
+    /**
+     * Gets the value of context with id `contextSymbol`
+     * @param contextSymbol - Name of the context to get
+     * @returns The context's value
+     */
+    static get<T>(contextSymbol: symbol): QContext<T> | undefined;
+    /**
+     * Prevents the propagation of the context further down
+     * @param contextSymbol - Name of the context to get
+     * @returns The context result
+     */
+    static reset(contextSymbol: symbol): void;
+    /**
+     * Updates the context's inner value with `newVal`
+     * @param newVal - New value to update the context with
+     */
+    update(newVal: T): void;
+    /**
+     * Updates the property of id `key` with `newVal` in the context's inner value
+     * @param key - Key to update
+     * @param newVal - New value to update the context's property with
+     */
+    updateEntry(key: keyof T, newVal: NonNullable<T>[keyof T]): void;
+    /**
+     * Updates the given properties their corresponding values in the context's inner value
+     * @param from - Object containing keys to update with their respective value
+     */
+    updateEntries(from: Record<keyof T, NonNullable<T>[keyof T]>): void;
+    /**
+     * Inner value of the context
+     */
+    get value(): T;
+}

package/dist/classes/QContext.svelte.js

@@ -0,0 +1,63 @@
+import { getContext, setContext } from "svelte";
+/**
+ * This class allows to manipulate reactive contexts more easily.
+ * It avoids having to pass a Svelte store down the components but rather use runes to keep the context reactive.
+ *
+ * This class should be used when the context has to be modified from a child component. Otherwise, using svelte's context API should be enough.
+ */
+export class QContext {
+    #state = $state();
+    constructor(contextSymbol, init) {
+        this.#state = init;
+        setContext(contextSymbol, this);
+    }
+    /**
+     * Gets the value of context with id `contextSymbol`
+     * @param contextSymbol - Name of the context to get
+     * @returns The context's value
+     */
+    static get(contextSymbol) {
+        return getContext(contextSymbol);
+    }
+    /**
+     * Prevents the propagation of the context further down
+     * @param contextSymbol - Name of the context to get
+     * @returns The context result
+     */
+    static reset(contextSymbol) {
+        setContext(contextSymbol, undefined);
+    }
+    /**
+     * Updates the context's inner value with `newVal`
+     * @param newVal - New value to update the context with
+     */
+    update(newVal) {
+        this.#state = newVal;
+    }
+    /**
+     * Updates the property of id `key` with `newVal` in the context's inner value
+     * @param key - Key to update
+     * @param newVal - New value to update the context's property with
+     */
+    updateEntry(key, newVal) {
+        if (!this.#state || typeof this.#state !== "object" || !Object.hasOwn(this.#state, key)) {
+            throw new Error(`${key.toString()} doesn't exist on ${this.#state}`);
+        }
+        this.#state[key] = newVal;
+    }
+    /**
+     * Updates the given properties their corresponding values in the context's inner value
+     * @param from - Object containing keys to update with their respective value
+     */
+    updateEntries(from) {
+        for (const key in from) {
+            this.updateEntry(key, from[key]);
+        }
+    }
+    /**
+     * Inner value of the context
+     */
+    get value() {
+        return this.#state;
+    }
+}

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

@@ -0,0 +1,48 @@
+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;
+type ScrollObserverOptions = {
+    debounce?: number;
+    horizontal?: boolean;
+};
+/**
+ * A scroll observer utility.
+ * @example
+ * ```js
+ * // Inside the <script> tag
+ * const scroll = new QScrollObserver();
+ *
+ * $inspect(scroll.direction)
+ * ```
+ *
+ * @param target - Element or selector of the element to add the scroll listener on
+ * @param options - Options of the observer
+ * @param options.horizontal - If set to `true`, observe horizontal scrolling rather than vertical
+ * @param options.debounce - Time in milliseconds between each observation update
+ */
+export default class QScrollObserver {
+    protected scrollType: ScrollType;
+    protected lastScroll: number;
+    protected horizontal: boolean;
+    protected clearTimer: (() => void) | null;
+    protected target: Exclude<Target, string> | null;
+    protected debounce: number;
+    protected handler: (e: Event) => void;
+    direction: Direction;
+    changedDirection: boolean;
+    delta: number;
+    inflectionPoint: number;
+    position: number;
+    constructor(target?: Target | null, { horizontal, debounce }?: ScrollObserverOptions);
+    protected getScrollPosition(target?: HTMLElement | typeof window | undefined): number;
+    protected baseHandler(e: Event): void;
+    protected updateDirection(target: HTMLElement): void;
+    protected handleDebounce(target: HTMLElement, debounce: number): void;
+    destroy(): void;
+}
+export {};

package/dist/classes/QScrollObserver.svelte.js

@@ -0,0 +1,107 @@
+import { onMount } from "svelte";
+import { elFromSelector } from "../utils";
+/**
+ * A scroll observer utility.
+ * @example
+ * ```js
+ * // Inside the <script> tag
+ * const scroll = new QScrollObserver();
+ *
+ * $inspect(scroll.direction)
+ * ```
+ *
+ * @param target - Element or selector of the element to add the scroll listener on
+ * @param options - Options of the observer
+ * @param options.horizontal - If set to `true`, observe horizontal scrolling rather than vertical
+ * @param options.debounce - Time in milliseconds between each observation update
+ */
+export default class QScrollObserver {
+    scrollType = {
+        window: "scrollY",
+        document: "scrollTop",
+    };
+    lastScroll;
+    horizontal = false;
+    clearTimer = null;
+    target = null;
+    debounce = 0;
+    handler;
+    direction = $state("down");
+    changedDirection = $state(false);
+    delta = $state(0);
+    inflectionPoint = $state(0);
+    position = $state(0);
+    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.lastScroll = 0;
+        this.position = 0;
+        this.inflectionPoint = 0;
+        this.direction = horizontal ? "right" : "down";
+        onMount(() => {
+            let parsedTarget = elFromSelector(target ?? null);
+            if (parsedTarget === null) {
+                console.warn(`The given target (${target}) is null, observing window instead`);
+                parsedTarget = window;
+            }
+            this.target = parsedTarget;
+            parsedTarget.addEventListener("scroll", this.handler, { capture: true });
+            return this.destroy.bind(this);
+        });
+    }
+    getScrollPosition(target = window) {
+        return Math.max(0, target === window
+            ? target[this.scrollType.window]
+            : target[this.scrollType.document]);
+    }
+    baseHandler(e) {
+        const eventTarget = e.target;
+        if (!eventTarget || !this.target || eventTarget !== this.target) {
+            return;
+        }
+        if (this.debounce) {
+            this.handleDebounce(this.target, this.debounce);
+        }
+        else {
+            this.updateDirection(this.target);
+        }
+    }
+    updateDirection(target) {
+        this.clearTimer?.();
+        const newScrollPosition = this.getScrollPosition(target);
+        this.position = newScrollPosition;
+        this.delta = newScrollPosition - this.lastScroll;
+        const newDirection = this.delta > 0 ? (this.horizontal ? "right" : "down") : this.horizontal ? "left" : "up";
+        this.changedDirection = newDirection !== this.direction;
+        if (this.changedDirection) {
+            this.direction = newDirection;
+            this.inflectionPoint = newScrollPosition;
+        }
+        this.lastScroll = newScrollPosition <= 0 ? 0 : newScrollPosition;
+    }
+    handleDebounce(target, debounce) {
+        if (this.clearTimer) {
+            return;
+        }
+        const timer = setTimeout(this.updateDirection.bind(this, target), debounce);
+        this.clearTimer = () => {
+            clearTimeout(timer);
+            this.clearTimer = null;
+        };
+    }
+    destroy() {
+        this.clearTimer?.();
+        this.clearTimer = null;
+        this.target?.removeEventListener("scroll", this.handler);
+        this.target = null;
+        this.direction = "down";
+        this.changedDirection = false;
+        this.delta = 0;
+        this.inflectionPoint = 0;
+        this.position = 0;
+    }
+}

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

@@ -0,0 +1,13 @@
+import { type HexValue, type QuaffColors, type Mode } from "../utils";
+type ThemeColors = Record<`${keyof QuaffColors}-${Mode}`, HexValue>;
+declare class QTheme {
+    themeColors: ThemeColors;
+    srcColor: string;
+    constructor();
+    private apply;
+    updateThemeColor(color: keyof ThemeColors, newVal: HexValue): void;
+    updateThemeColors(colors: Partial<ThemeColors>): void;
+    setTheme(from: string): void;
+}
+declare const _default: QTheme;
+export default _default;

package/dist/classes/QTheme.svelte.js

@@ -0,0 +1,62 @@
+import { generateColors } from "../utils";
+function extractColorFromCssVar(cssVar) {
+    const rootStyles = getComputedStyle(document.documentElement);
+    // remove var(...) to get only the color
+    const varName = cssVar.replace(/var\(([a-z0-9-]+)\)/, "$1");
+    return rootStyles.getPropertyValue(varName).trim();
+}
+function prepareThemeColors(from) {
+    if (from.startsWith("var(")) {
+        from = extractColorFromCssVar(from);
+    }
+    const theme = generateColors(from);
+    //@ts-expect-error The properties are added in the next for loop
+    const themeColors = {};
+    let mode;
+    for (mode in theme) {
+        let color;
+        for (color in theme[mode]) {
+            const cssColor = `${color}-${mode}`;
+            themeColors[cssColor] = theme[mode][color];
+        }
+    }
+    return themeColors;
+}
+class QTheme {
+    themeColors = $state({});
+    srcColor = $state("#0039b4");
+    constructor() {
+        this.themeColors = prepareThemeColors(this.srcColor);
+    }
+    apply() {
+        const root = document.documentElement;
+        if (root === null) {
+            return;
+        }
+        let colorName;
+        for (colorName in this.themeColors) {
+            root.style.setProperty(`--${colorName}`, this.themeColors[colorName]);
+        }
+    }
+    updateThemeColor(color, newVal) {
+        this.themeColors[color] = newVal;
+        this.apply();
+    }
+    updateThemeColors(colors) {
+        let colorName;
+        for (colorName in colors) {
+            const color = colors[colorName];
+            if (color) {
+                this.themeColors[colorName] = color;
+            }
+        }
+        this.apply();
+    }
+    setTheme(from) {
+        const newTheme = prepareThemeColors(from);
+        this.themeColors = newTheme;
+        this.srcColor = from;
+        this.apply();
+    }
+}
+export default new QTheme();

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

@@ -0,0 +1,27 @@
+declare class Quaff {
+    version: string;
+    private static readonly breakpointList;
+    readonly breakpoints: {
+        currentWidth: number;
+        current: "xs" | "sm" | "md" | "lg" | "xl";
+        isMoreThan(breakpoint: "xs" | "sm" | "md" | "lg" | "xl", included?: boolean): boolean;
+        isLessThan(breakpoint: "xs" | "sm" | "md" | "lg" | "xl", included?: boolean): boolean;
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    };
+    router: import("@sveltejs/kit").Page<Record<string, string>, string | null>;
+    protected dark: boolean;
+    init(): void;
+    protected toggleDarkMode(): void;
+    protected setDarkMode(newVal: boolean): void;
+    get darkMode(): {
+        readonly isActive: boolean;
+        toggle: () => void;
+        set: (newVal: boolean) => void;
+    };
+}
+declare const _default: Quaff;
+export default _default;

package/dist/classes/Quaff.svelte.js

@@ -0,0 +1,91 @@
+import { onMount } from "svelte";
+import { innerWidth } from "svelte/reactivity/window";
+import { version } from "../helpers";
+import { page } from "$app/state";
+class Quaff {
+    version = version;
+    static breakpointList = {
+        xs: 0,
+        sm: 600,
+        md: 960,
+        lg: 1280,
+        xl: 1920,
+    };
+    breakpoints = $derived.by(() => {
+        const currentWidth = innerWidth.current;
+        let current;
+        if (!currentWidth || currentWidth < 600) {
+            current = "xs";
+        }
+        else if (currentWidth < 960) {
+            current = "sm";
+        }
+        else if (currentWidth < 1280) {
+            current = "md";
+        }
+        else if (currentWidth < 1920) {
+            current = "lg";
+        }
+        else {
+            current = "xl";
+        }
+        return {
+            ...Quaff.breakpointList,
+            currentWidth: currentWidth || 0,
+            current,
+            isMoreThan(breakpoint, included = false) {
+                if (!currentWidth) {
+                    return false;
+                }
+                const breakpointWidth = this[breakpoint];
+                return included ? currentWidth >= breakpointWidth : currentWidth > breakpointWidth;
+            },
+            isLessThan(breakpoint, included = false) {
+                if (!currentWidth) {
+                    return false;
+                }
+                const breakpointWidth = this[breakpoint];
+                return included ? currentWidth <= breakpointWidth : currentWidth < breakpointWidth;
+            },
+        };
+    });
+    router = $derived(page);
+    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;
+            }
+        });
+    }
+    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);
+    }
+    setDarkMode(newVal) {
+        this.dark = newVal;
+    }
+    get darkMode() {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        return {
+            get isActive() {
+                return self.dark;
+            },
+            toggle: () => this.toggleDarkMode(),
+            set: (newVal) => this.setDarkMode(newVal),
+        };
+    }
+}
+export default new Quaff();

package/dist/components/avatar/QAvatar.scss

@@ -0,0 +1,101 @@
+@use "$css/variables";
+
+@layer q-avatar {
+  // Basic styles
+  .q-avatar {
+    height: var(--size);
+    width: var(--size);
+
+    & > img,
+    & > video {
+      object-fit: cover;
+      object-position: center;
+      aspect-ratio: 1;
+      width: 100%;
+      height: 100%;
+    }
+    transition:
+      variables.$speed3 transform,
+      variables.$speed3 border-radius,
+      variables.$speed3 padding;
+    border-radius: 0;
+
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    font-size: 1rem;
+    text-transform: uppercase;
+
+    overflow: hidden;
+
+    -webkit-user-select: none;
+    -moz-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
+
+    &.circle {
+      margin: 0;
+    }
+  }
+
+  // Sizes
+  $sizes: (
+    "xs": 0,
+    "sm": 1,
+    "md": 2,
+    "lg": 3,
+    "xl": 4,
+  );
+
+  .q-avatar {
+    @each $size, $val in $sizes {
+      &--#{$size} {
+        --size: calc(2rem + #{$val} * 0.5rem);
+      }
+    }
+  }
+
+  // Border radius
+  $positions-y: "top", "bottom";
+  $positions-x: "right", "left";
+
+  .q-avatar {
+    border-radius: 50%;
+
+    &--square {
+      border-radius: 0;
+    }
+
+    &--top-right-round {
+      border-bottom-left-radius: 0;
+    }
+    &--top-left-round {
+      border-bottom-right-radius: 0;
+    }
+    &--bottom-right-round {
+      border-top-left-radius: 0;
+    }
+    &--bottom-left-round {
+      border-top-right-radius: 0;
+    }
+
+    @each $pos-y in $positions-y {
+      &--#{$pos-y}-round {
+        @extend .q-avatar--#{$pos-y}-left-round;
+        @extend .q-avatar--#{$pos-y}-right-round;
+      }
+    }
+
+    @each $pos-x in $positions-x {
+      &--#{$pos-x}-round {
+        @extend .q-avatar--top-#{$pos-x}-round;
+        @extend .q-avatar--bottom-#{$pos-x}-round;
+      }
+    }
+
+    &--round {
+      border-radius: 0.5rem;
+    }
+  }
+}