@vollowx/seele 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 - 2025 Vollow
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# Standard Extensible Elements
+
+**SEELE** is a modern, lightweight [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) library. It provides a set of highly customizable UI components that follow the [Material Design 3](https://m3.material.io/) guidelines out of the box, while being designed for easy extension and restyling.
+
+Visit the [website of SEELE](https://seele.v9.nz/) for documentation and demos.
+
+## Features
+
+- **Material Design 3**: Ready-to-use components following the latest Material guidelines.
+- **Web Components**: Framework-agnostic. Works with vanilla HTML or any framework.
+- **Extensible**: Built to be extended. Create your own design system on top of SEELE's logic.
+- **Lightweight**: Built on [Lit](https://lit.dev/) and [floating-ui](https://floating-ui.com/) only, ensuring fast performance and small bundle sizes.
+- **Accessible**: Designed with accessibility in mind (using `ElementInternals` and standard ARIA patterns).
+
+## Installation
+
+Install SEELE using your preferred package manager:
+
+```bash
+# npm
+npm install @vollowx/seele
+
+# pnpm
+pnpm add @vollowx/seele
+
+# yarn
+yarn add @vollowx/seele
+
+# bun
+bun add @vollowx/seele
+```
+
+## Usage
+
+### Importing Components
+
+You can import the entire library or individual components to keep your bundle size small.
+
+```javascript
+// Import all components
+import '@vollowx/seele';
+
+// OR Import specific components (Recommended)
+import '@vollowx/seele/m3/button/common-button.js';
+import '@vollowx/seele/m3/checkbox.js';
+```
+
+### Using Components
+
+Once imported, use the components just like standard HTML tags.
+
+```html
+<md-button variant="filled">Filled Button</md-button>
+<md-button variant="outlined">Outlined Button</md-button>
+
+<label>
+  <md-checkbox checked></md-checkbox>
+  Labelled Checkbox
+</label>
+```
+
+### Theming
+
+SEELE components use CSS variables for styling. Currently, the global Material Design 3 token variables are not included in the JavaScript bundle.
+
+To style the components correctly, you need to define the necessary CSS variables in your project. You can find reference implementations in [vollowx/seele-docs](https://github.com/vollowx/seele-docs/) or the `dev` folder of this repository.
+
+## Browser Supporty
+
+SEELE relies on modern web standards like `ElementInternals`.
+
+- **Chromium**: `>= 125.0`
+- **Firefox**: `>= 126.0`
+
+## Resources
+
+- [Roadmap](./ROADMAP.md)
+- [Contributing Guide](./CONTRIBUTING.md)
+- [License](./LICENSE)

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@vollowx/seele",
+  "version": "0.7.0",
+  "description": "Standard Extensible Elements. A web components library that can be styled and extended freely, pre-providing components in Material Design 3.",
+  "author": "vollowx",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/all.js",
+  "module": "./src/all.js",
+  "exports": {
+    ".": "./src/all.js",
+    "./m3/*": "./src/m3/*.js",
+    "./base/*": "./src/base/*.js"
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "web-components",
+    "material-design",
+    "material-3",
+    "lit",
+    "ui-components"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vollowx/seele.git"
+  },
+  "scripts": {
+    "dev": "wds",
+    "dev:styles": "node scripts/convert-styles.mjs watch",
+    "build": "bun run build:styles && bun run build:components",
+    "build:styles": "node scripts/convert-styles.mjs build",
+    "build:components": "tsc",
+    "cleanup": "node scripts/cleanup.mjs",
+    "prepublishOnly": "bun cleanup && bun run build",
+    "format": "prettier . --check",
+    "format:fix": "prettier . --check --write",
+    "format:sortcss": "bunx postcss \"src/**/*.css\" --replace --no-map"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.11.0",
+    "@types/node": "^25.0.3",
+    "@web/dev-server": "^0.4.6",
+    "@web/dev-server-esbuild": "^1.0.4",
+    "chokidar": "^5.0.0",
+    "lightningcss": "^1.30.2",
+    "postcss": "^8.5.6",
+    "postcss-cli": "^11.0.1",
+    "postcss-sorting": "^9.1.0",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.4",
+    "lit": "^3.3.2",
+    "tslib": "^2.8.1"
+  }
+}

package/src/all.js

@@ -0,0 +1,19 @@
+export { M3Button } from './m3/button/common-button.js';
+export { M3ButtonToggle } from './m3/button/common-button-toggle.js';
+export { M3IconButton } from './m3/button/icon-button.js';
+export { M3IconButtonToggle } from './m3/button/icon-button-toggle.js';
+export { M3FilledTextField } from './m3/text-field/filled-text-field.js';
+export { M3OutlinedTextField } from './m3/text-field/outlined-text-field.js';
+export { MdFilledSelect } from './m3/select/filled-select.js';
+export { MdOutlinedSelect } from './m3/select/outlined-select.js';
+export { M3Checkbox } from './m3/checkbox.js';
+export { M3FAB } from './m3/fab.js';
+export { M3Item } from './m3/item.js';
+export { M3List } from './m3/list.js';
+export { M3Menu } from './m3/menu.js';
+export { M3MenuItem } from './m3/menu-item.js';
+export { M3Option } from './m3/option.js';
+export { M3Ripple } from './m3/ripple.js';
+export { M3Switch } from './m3/switch.js';
+export { M3Tooltip } from './m3/tooltip.js';
+export { M3Toolbar } from './m3/toolbar.js';

package/src/base/button.js

@@ -0,0 +1,61 @@
+import { __decorate } from "tslib";
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { InternalsAttached, internals } from './mixins/internals-attached.js';
+import { FormAssociated } from './mixins/form-associated.js';
+import { hiddenStyles } from './hidden-styles.css.js';
+const Base = FormAssociated(InternalsAttached(LitElement));
+export class Button extends Base {
+    static { this.styles = [hiddenStyles]; }
+    constructor() {
+        super();
+        this.type = 'button';
+        this.#handleKeyDown = (e) => {
+            if (e.key !== ' ' && e.key !== 'Enter')
+                return;
+            e.preventDefault();
+            e.stopPropagation();
+            if (e.key === 'Enter')
+                this.click();
+        };
+        this.#handleKeyUp = (e) => {
+            if (e.key === ' ') {
+                e.preventDefault();
+                e.stopPropagation();
+                this.click();
+            }
+        };
+        this.#handleClick = () => {
+            if (this.type !== 'button')
+                this[internals].form?.[this.type]();
+        };
+        this[internals].role = 'button';
+        this.updateState();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('keydown', this.#handleKeyDown);
+        this.addEventListener('keyup', this.#handleKeyUp);
+        this.addEventListener('click', this.#handleClick);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('keydown', this.#handleKeyDown);
+        this.removeEventListener('keyup', this.#handleKeyUp);
+        this.removeEventListener('click', this.#handleClick);
+    }
+    updated(changed) {
+        if (changed.has('disabled'))
+            this.updateState();
+    }
+    updateState() {
+        this.tabIndex = this.disabled ? -1 : 0;
+        this[internals].ariaDisabled = String(this.disabled);
+    }
+    #handleKeyDown;
+    #handleKeyUp;
+    #handleClick;
+}
+__decorate([
+    property({ reflect: true })
+], Button.prototype, "type", void 0);

package/src/base/checkbox.js

@@ -0,0 +1,118 @@
+import { __decorate } from "tslib";
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { FormAssociated } from './mixins/form-associated.js';
+import { InternalsAttached, internals } from './mixins/internals-attached.js';
+import { hiddenStyles } from './hidden-styles.css.js';
+const PROPERTY_FROM_ARIA_CHECKED = {
+    true: 'checked',
+    false: 'unchecked',
+    mixed: 'indeterminate',
+};
+const Base = FormAssociated(InternalsAttached(LitElement));
+export class Checkbox extends Base {
+    static { this.styles = [hiddenStyles]; }
+    constructor() {
+        super();
+        this.checked = false;
+        this.indeterminate = false;
+        this.required = false;
+        this.#handleClick = (e) => {
+            e.stopPropagation();
+            e.preventDefault();
+            this.#toggleChecked();
+        };
+        this.#handleKeyDown = (e) => {
+            if (e.key === ' ') {
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        };
+        this.#handleKeyUp = (e) => {
+            if (e.key === ' ') {
+                e.preventDefault();
+                e.stopPropagation();
+                this.#toggleChecked();
+            }
+        };
+        this[internals].role = 'checkbox';
+        this.checked = this.hasAttribute('checked');
+        this.indeterminate = this.hasAttribute('indeterminate');
+        this.updateState();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('click', this.#handleClick);
+        this.addEventListener('keydown', this.#handleKeyDown);
+        this.addEventListener('keyup', this.#handleKeyUp);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('click', this.#handleClick);
+        this.removeEventListener('keydown', this.#handleKeyDown);
+        this.removeEventListener('keyup', this.#handleKeyUp);
+    }
+    updated(changed) {
+        if (changed.has('checked') ||
+            changed.has('disabled') ||
+            changed.has('indeterminate') ||
+            changed.has('required')) {
+            this.updateState();
+        }
+    }
+    updateState() {
+        const prevAriaChecked = this[internals]
+            .ariaChecked;
+        this[internals].states.delete('was-unchecked');
+        this[internals].states.delete('was-checked');
+        this[internals].states.delete('was-indeterminate');
+        if (prevAriaChecked && PROPERTY_FROM_ARIA_CHECKED[prevAriaChecked]) {
+            this[internals].states.add(`was-${PROPERTY_FROM_ARIA_CHECKED[prevAriaChecked]}`);
+        }
+        this[internals].ariaChecked = this.indeterminate
+            ? 'mixed'
+            : this.checked
+                ? 'true'
+                : 'false';
+        const currentAriaChecked = this[internals]
+            .ariaChecked;
+        this[internals].states.delete('unchecked');
+        this[internals].states.delete('checked');
+        this[internals].states.delete('indeterminate');
+        this[internals].states.add(`${PROPERTY_FROM_ARIA_CHECKED[currentAriaChecked]}`);
+        this.tabIndex = this.disabled ? -1 : 0;
+        this[internals].ariaDisabled = String(this.disabled);
+        this[internals].setFormValue(this.checked ? 'on' : null);
+        if (this.required && !this.checked) {
+            this[internals].setValidity({ valueMissing: true }, 
+            // TODO: I18n
+            'Please check this box if you want to proceed.');
+        }
+        else {
+            this[internals].setValidity({});
+        }
+    }
+    #handleClick;
+    #handleKeyDown;
+    #handleKeyUp;
+    #toggleChecked() {
+        if (this.disabled)
+            return;
+        this.checked = !this.checked;
+        this.indeterminate = false;
+        this.dispatchEvent(new CustomEvent('change', {
+            bubbles: true,
+            composed: true,
+            detail: this.checked,
+        }));
+    }
+}
+__decorate([
+    property({ type: Boolean })
+], Checkbox.prototype, "checked", void 0);
+__decorate([
+    property({ type: Boolean })
+], Checkbox.prototype, "indeterminate", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], Checkbox.prototype, "required", void 0);

package/src/base/controllers/list-controller.js

@@ -0,0 +1,96 @@
+import { getIndexByLetter } from '../menu-utils.js';
+export class ListController {
+    constructor(host, config) {
+        this._focusedIndex = -1;
+        this.searchString = '';
+        this.searchTimeout = null;
+        const { isItem, getPossibleItems, blurItem, focusItem, wrapNavigation } = config;
+        (this.host = host).addController(this);
+        this.isItem = isItem;
+        this.getPossibleItems = getPossibleItems;
+        this.blurItem = blurItem;
+        this.focusItem = focusItem;
+        this.wrapNavigation = wrapNavigation;
+    }
+    hostConnected() { }
+    hostDisconnected() { }
+    get items() {
+        return this.getPossibleItems().filter(this.isItem);
+    }
+    get currentIndex() {
+        const items = this.getPossibleItems().filter(this.isItem);
+        return items.findIndex((item) => item.focused) ?? -1;
+    }
+    handleType(char) {
+        const searchString = this.getSearchString(char);
+        const items = this.items;
+        const optionsText = items.map((item) => item.innerText);
+        const searchIndex = getIndexByLetter(optionsText, searchString, this.currentIndex + 1);
+        if (searchIndex >= 0) {
+            this._focusItem(items[searchIndex]);
+            return true;
+        }
+        else {
+            if (this.searchTimeout)
+                window.clearTimeout(this.searchTimeout);
+            this.searchString = '';
+            return false;
+        }
+    }
+    getSearchString(char) {
+        if (this.searchTimeout) {
+            window.clearTimeout(this.searchTimeout);
+        }
+        this.searchTimeout = window.setTimeout(() => {
+            this.searchString = '';
+        }, 500);
+        this.searchString += char;
+        return this.searchString;
+    }
+    clearSearch() {
+        this.searchString = '';
+        if (this.searchTimeout) {
+            window.clearTimeout(this.searchTimeout);
+            this.searchTimeout = null;
+        }
+    }
+    _focusItem(item) {
+        if (this._focusedIndex !== -1)
+            this._blurItem(this.items[this._focusedIndex]);
+        this.focusItem(item);
+        this._focusedIndex = this.items.indexOf(item);
+    }
+    _blurItem(item) {
+        this.blurItem(item);
+        this._focusedIndex = -1;
+    }
+    focusFirstItem() {
+        this._focusItem(this.items[0]);
+    }
+    focusLastItem() {
+        this._focusItem(this.items[this.items.length - 1]);
+    }
+    focusNextItem() {
+        const count = this.items.length;
+        if (count === 0)
+            return;
+        let nextIndex = this._focusedIndex + 1;
+        if (nextIndex >= count) {
+            nextIndex = this.wrapNavigation() ? count - 1 : 0;
+        }
+        this._focusItem(this.items[nextIndex]);
+    }
+    focusPreviousItem() {
+        const count = this.items.length;
+        if (count === 0)
+            return;
+        let prevIndex = this._focusedIndex - 1;
+        if (prevIndex < 0) {
+            prevIndex = this.wrapNavigation() ? 0 : count - 1;
+        }
+        this._focusItem(this.items[prevIndex]);
+    }
+    handleSlotChange() {
+        this._focusedIndex = this.currentIndex;
+    }
+}

package/src/base/controllers/popover-controller.js

@@ -0,0 +1,163 @@
+import { internals, } from '../mixins/internals-attached.js';
+import { autoUpdate, computePosition, arrow, flip, offset, shift, } from '@floating-ui/dom';
+export function transformOriginFromArrow(placement, arrowData) {
+    const { x: arrowX, y: arrowY } = arrowData || {};
+    const [side] = placement.split('-');
+    let originX = '';
+    let originY = '';
+    if (side === 'top') {
+        originX = arrowX != null ? `${arrowX}px` : 'center';
+        originY = 'bottom';
+    }
+    else if (side === 'bottom') {
+        originX = arrowX != null ? `${arrowX}px` : 'center';
+        originY = 'top';
+    }
+    else if (side === 'left') {
+        originX = 'right';
+        originY = arrowY != null ? `${arrowY}px` : 'center';
+    }
+    else if (side === 'right') {
+        originX = 'left';
+        originY = arrowY != null ? `${arrowY}px` : 'center';
+    }
+    return `${originX} ${originY}`;
+}
+export class PopoverController {
+    get open() {
+        return this._open;
+    }
+    constructor(host, config) {
+        this._open = false;
+        // Different from those in the Tooltip, these timers are used to manage the
+        // animation timing.
+        this.#openTimer = null;
+        this.#closeTimer = null;
+        // TODO: Provide the ability to specify an arrow element.
+        this._dummyArrow = document.createElement('div');
+        this.#handleClickOutside = (event) => {
+            const trigger = this.config.trigger();
+            const popover = this.config.popover();
+            const path = event.composedPath();
+            if (trigger && path.includes(trigger))
+                return;
+            if (popover && path.includes(popover))
+                return;
+            this.config.onClickOutside?.();
+        };
+        (this.host = host).addController(this);
+        this.config = config;
+    }
+    hostConnected() {
+        // Initial state
+        if (!this._open) {
+            this.host[internals].states.add('closed');
+        }
+    }
+    hostDisconnected() {
+        this.cleanupAutoUpdate?.();
+        window.removeEventListener('pointerup', this.#handleClickOutside);
+    }
+    // Different from those in the Tooltip, these timers are used to manage the
+    // animation timing.
+    #openTimer;
+    #closeTimer;
+    async animateOpen() {
+        if (this._open)
+            return;
+        this._open = true;
+        // Prevent the click that triggered the open from immediately closing it
+        // TODO: Use a global event listener to manage this more effectively
+        setTimeout(() => {
+            if (this._open) {
+                window.addEventListener('pointerup', this.#handleClickOutside);
+            }
+        }, 0);
+        clearTimeout(this.#openTimer);
+        clearTimeout(this.#closeTimer);
+        const openDuration = this.config.durations.open();
+        this.host[internals].states.delete('closed');
+        this.host[internals].states.delete('closing');
+        const trigger = this.config.trigger();
+        const popover = this.config.popover();
+        if (trigger && popover) {
+            this.cleanupAutoUpdate?.();
+            this.cleanupAutoUpdate = autoUpdate(trigger, popover, () => this.reposition());
+            // Initial position
+            await this.reposition();
+        }
+        if (openDuration === 0) {
+            this.host[internals].states.add('opened');
+        }
+        else {
+            // Wait for a frame to ensure the element is rendered with base styles
+            // e.g. (opacity 0) before adding the opening state e.g. (opacity 1) to
+            // trigger transition.
+            requestAnimationFrame(() => {
+                if (this._open) {
+                    this.host[internals].states.add('opening');
+                }
+            });
+            this.#openTimer = setTimeout(() => {
+                this.host[internals].states.delete('opening');
+                this.host[internals].states.add('opened');
+            }, openDuration);
+        }
+    }
+    async animateClose() {
+        if (!this._open)
+            return;
+        this._open = false;
+        window.removeEventListener('pointerup', this.#handleClickOutside);
+        clearTimeout(this.#openTimer);
+        clearTimeout(this.#closeTimer);
+        const closeDuration = this.config.durations.close();
+        const wasOpened = this.host[internals].states.has('opened');
+        this.host[internals].states.delete('opened');
+        this.host[internals].states.delete('opening');
+        if (closeDuration === 0 || !wasOpened) {
+            this.cleanup();
+            this.host[internals].states.delete('closing');
+            this.host[internals].states.add('closed');
+        }
+        else {
+            this.host[internals].states.add('closing');
+            this.#closeTimer = setTimeout(() => {
+                this.cleanup();
+                this.host[internals].states.delete('closing');
+                this.host[internals].states.add('closed');
+            }, closeDuration);
+        }
+    }
+    cleanup() {
+        this.cleanupAutoUpdate?.();
+        this.cleanupAutoUpdate = undefined;
+    }
+    reposition() {
+        const trigger = this.config.trigger();
+        const popover = this.config.popover();
+        if (!trigger || !popover)
+            return Promise.resolve();
+        return computePosition(trigger, popover, {
+            placement: this.config.positioning.placement(),
+            strategy: this.config.positioning.strategy(),
+            middleware: [
+                offset(this.config.positioning.offset()),
+                flip({ padding: this.config.positioning.windowPadding() }),
+                shift({
+                    padding: this.config.positioning.windowPadding(),
+                    crossAxis: true,
+                }),
+                arrow({ element: this._dummyArrow }),
+            ],
+        }).then(({ x, y, strategy, placement, middlewareData }) => {
+            Object.assign(popover.style, {
+                left: `${x}px`,
+                top: `${y}px`,
+                position: strategy,
+                transformOrigin: transformOriginFromArrow(placement, middlewareData.arrow),
+            });
+        });
+    }
+    #handleClickOutside;
+}

package/src/base/field.js

@@ -0,0 +1,3 @@
+import { LitElement } from 'lit';
+export class Field extends LitElement {
+}

package/src/base/hidden-styles.css.js

@@ -0,0 +1,2 @@
+import { css } from 'lit';
+export const hiddenStyles = css `:host([hidden]){visibility:hidden;display:none}`;