@itenthusiasm/custom-elements 0.7.0 → 0.9.0

package/CheckboxGroup/types/solid.d.ts

@@ -0,0 +1,29 @@
+import type { CheckboxGroup } from "../index.js";
+
+declare module "solid-js" {
+  namespace JSX {
+    interface HTMLElementTags {
+      "checkbox-group": CheckboxGroupHTMLAttributes<CheckboxGroup>;
+    }
+
+    interface CheckboxGroupHTMLAttributes<T> extends HTMLAttributes<T> {
+      value?: CheckboxGroup["value"];
+      name?: CheckboxGroup["name"];
+      disabled?: CheckboxGroup["disabled"];
+      required?: CheckboxGroup["required"];
+      min?: CheckboxGroup["min"] | number;
+      max?: CheckboxGroup["max"] | number;
+      manual?: CheckboxGroup["manual"];
+      valuemissingerror?: CheckboxGroup["valueMissingError"];
+      "attr:valuemissingerror"?: CheckboxGroup["valueMissingError"];
+      rangeunderflowerror?: CheckboxGroup["rangeUnderflowError"];
+      "attr:rangeunderflowerror"?: CheckboxGroup["rangeUnderflowError"];
+      rangeoverflowerror?: CheckboxGroup["rangeOverflowError"];
+      "attr:rangeoverflowerror"?: CheckboxGroup["rangeOverflowError"];
+    }
+
+    interface ExplicitBoolAttributes {
+      checked?: boolean;
+    }
+  }
+}

package/CheckboxGroup/types/svelte.d.ts

@@ -0,0 +1,20 @@
+import type { CheckboxGroup } from "../index.js";
+
+declare module "svelte/elements" {
+  interface SvelteHTMLElements {
+    "checkbox-group": HTMLCheckboxGroupAttributes;
+  }
+
+  interface HTMLCheckboxGroupAttributes extends HTMLAttributes<CheckboxGroup> {
+    value?: CheckboxGroup["value"] | null;
+    name?: CheckboxGroup["name"] | null;
+    disabled?: CheckboxGroup["disabled"] | null;
+    required?: CheckboxGroup["required"] | null;
+    min?: CheckboxGroup["min"] | number | null;
+    max?: CheckboxGroup["max"] | number | null;
+    manual?: CheckboxGroup["manual"] | null;
+    valuemissingerror?: CheckboxGroup["valueMissingError"] | null;
+    rangeunderflowerror?: CheckboxGroup["rangeUnderflowError"] | null;
+    rangeoverflowerror?: CheckboxGroup["rangeOverflowError"] | null;
+  }
+}

package/CheckboxGroup/types/vue.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, PublicProps, EmitFn } from "vue";
+import type { CheckboxGroup } from "../index.js";
+
+declare module "vue" {
+  // Helper Types
+  type Booleanish = boolean | "true" | "false";
+  type VueEmitMap<T extends GlobalEventHandlersEventMap> = EmitFn<{ [K in keyof T]: (event: T[K]) => void }>;
+  interface VueGlobalHTMLAttributes extends HTMLAttributes, Omit<PublicProps, "class" | "style"> {}
+
+  /* -------------------- Register Elements -------------------- */
+  interface GlobalComponents {
+    "checkbox-group": new () => CheckboxGroupVueSFCType;
+  }
+
+  interface IntrinsicElementAttributes {
+    "checkbox-group": CheckboxGroupHTMLAttributes;
+  }
+
+  /* -------------------- Checkbox Group -------------------- */
+  interface CheckboxGroupHTMLAttributes extends VueGlobalHTMLAttributes {
+    value?: CheckboxGroup["value"];
+    name?: CheckboxGroup["name"];
+    disabled?: CheckboxGroup["disabled"];
+    required?: CheckboxGroup["required"];
+    min?: CheckboxGroup["min"] | number;
+    max?: CheckboxGroup["max"] | number;
+    manual?: CheckboxGroup["manual"];
+    valuemissingerror?: CheckboxGroup["valueMissingError"];
+    rangeunderflowerror?: CheckboxGroup["rangeUnderflowError"];
+    rangeoverflowerror?: CheckboxGroup["rangeOverflowError"];
+  }
+
+  interface CheckboxGroupVueSFCType extends CheckboxGroup {
+    /** @deprecated Only for use by Vue's templating language */
+    $props: CheckboxGroupHTMLAttributes;
+
+    /** @deprecated Only for use by Vue's templating language */
+    $emit: VueEmitMap<HTMLElementEventMap>;
+  }
+}

package/Combobox/ComboboxField.d.ts

@@ -1,14 +1,4 @@
 export default ComboboxField;
-export type ExposedInternals = Pick<ElementInternals, "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity">;
-export type FieldPropertiesAndMethods = Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity">;
-/**
- * @typedef {Pick<ElementInternals,
-     "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity"
-   >} ExposedInternals
- */
-/**
- * @typedef {Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity">} FieldPropertiesAndMethods
- */
 /** @implements {ExposedInternals} @implements {FieldPropertiesAndMethods} */
 declare class ComboboxField extends HTMLElement implements ExposedInternals, FieldPropertiesAndMethods {
     /** @returns {true} */
@@ -157,7 +147,7 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
     set filter(value: boolean);
     /** Activates a textbox that can be used to filter the list of `combobox` `option`s. @returns {boolean} */
     get filter(): boolean;
-    set filterMethod(value: Extract<number | typeof Symbol.iterator | "normalize" | "link" | "search" | "small" | "sub" | "sup" | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "big" | "blink" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "strike" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">);
+    set filterMethod(value: Extract<number | "normalize" | typeof Symbol.iterator | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "link" | "search" | "small" | "sub" | "sup" | "big" | "blink" | "strike" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">);
     /**
      * Determines the method used to filter the `option`s as the user types.
      * - `startsWith`: {@link String.startsWith} will be used to filter the `option`s.
@@ -167,7 +157,7 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
      *
      * @returns {Extract<keyof String, "startsWith" | "includes">}
      */
-    get filterMethod(): Extract<number | typeof Symbol.iterator | "normalize" | "link" | "search" | "small" | "sub" | "sup" | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "big" | "blink" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "strike" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">;
+    get filterMethod(): Extract<number | "normalize" | typeof Symbol.iterator | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "link" | "search" | "small" | "sub" | "sup" | "big" | "blink" | "strike" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">;
     set valueIs(value: "unclearable" | "clearable" | "anyvalue");
     /**
      * Indicates how a `combobox`'s value will behave.
@@ -232,6 +222,8 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
     /** @private @type {boolean} */ private [editingKey];
     #private;
 }
+import type { ExposedInternals } from "../types/helpers.js";
+import type { FieldPropertiesAndMethods } from "../types/helpers.js";
 import ComboboxOption from "./ComboboxOption.js";
 import type { ListboxWithChildren } from "./types/helpers.js";
 /** Internally used to retrieve the value that the `combobox` had when it was focused. */

package/Combobox/ComboboxField.js

@@ -1,4 +1,5 @@
 /** @import {ListboxWithChildren} from "./types/helpers.js" */
+/** @import {ExposedInternals, FieldPropertiesAndMethods} from "../types/helpers.js" */
 import { setAttributeFor } from "../utils/dom.js";
 import ComboboxOption from "./ComboboxOption.js";
 import ComboboxListbox from "./ComboboxListbox.js";
@@ -21,16 +22,6 @@ const attrs = Object.freeze({
   "aria-expanded": "aria-expanded",
 });
 
-/** 
- * @typedef {Pick<ElementInternals,
-     "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity"
-   >} ExposedInternals
- */
-
-/**
- * @typedef {Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity">} FieldPropertiesAndMethods
- */
-
 /** @implements {ExposedInternals} @implements {FieldPropertiesAndMethods} */
 class ComboboxField extends HTMLElement {
   /* ------------------------------ Custom Element Settings ------------------------------ */
@@ -588,7 +579,7 @@ class ComboboxField extends HTMLElement {
   }
 
   set disabled(value) {
-    this.toggleAttribute("disabled", Boolean(value));
+    this.toggleAttribute("disabled", value);
   }
 
   /** @returns {HTMLInputElement["required"]} */
@@ -597,7 +588,7 @@ class ComboboxField extends HTMLElement {
   }
 
   set required(value) {
-    this.toggleAttribute("required", Boolean(value));
+    this.toggleAttribute("required", value);
   }
 
   /**
@@ -628,7 +619,7 @@ class ComboboxField extends HTMLElement {
   }
 
   set filter(value) {
-    this.toggleAttribute("filter", Boolean(value));
+    this.toggleAttribute("filter", value);
   }
 
   /**

package/Combobox/README.md

@@ -2,18 +2,6 @@
 
 A group of robust, extendable and stylable [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) which work together to function as an accessible [`combobox`](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
 
-## Features and Benefits
-
-- **Framework Agnostic**: Because this component simply uses custom `HTMLElement`s, it works seamlessly in all JS Frameworks (and in pure-JS applications if that's what you fancy).
-- **Integrates with Native Web Forms**: This component [integrates](https://web.dev/articles/more-capable-form-controls) with the web's native `<form>` element, meaning that its value will be seen in the form's [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and will be automatically [sent to the server](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) when the form is submitted &mdash; all without writing a single line of JS.
-- **Works with Various Form Libraries**: The component emits standard DOM events like [`input`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) and [`change`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event), enabling it to work naturally with reputable form libraries (e.g., the [`Form Observer`](https://github.com/enthusiastic-js/form-observer), [`Conform`](https://conform.guide/), and [`React Hook Form`](https://react-hook-form.com/)).
-- **Progressive Enhacement**: When used in [`Select Enhacing Mode`](#select-enhancing-mode), the component will fallback to a regular `<select>` element if JS is disabled or unavailable for your users. This means your forms will _always_ be fully usable and accessible.
-- **Highly Customizable**: The component is flexible enough to work with whatever CSS you provide, and its functionality can be enhanced or overriden through [class extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends).
-- **Performant**: Unlike many other alternatives, this component has been cleverly designed to work without complex state management tools or aggressive DOM Tree manipulation. This makes it a fast and memory-efficient solution.
-- **No Dependencies**: The component is built on the native web platform instead of extending other frameworks or libraries, guaranteeing your bundle size remains as small as possible.
-
-<!-- TODO: Link to article explaining how progressively-enhanced Form Controls _greatly_ simplify frontend code. -->
-
 ## Install
 
 ```
@@ -220,6 +208,19 @@ import type {} from "@itenthusiasm/custom-elements/Combobox/types/react";
 // etc. ...
 ```
 
+The component also ships with types that enhance the native DOM methods if you need them:
+
+```ts
+import type {} from "@itenthusiasm/custom-elements/types/dom";
+// Or more specifically, import type {} from "@itenthusiasm/custom-elements/Combobox/types/dom";
+
+// These variables will be properly typed by TypeScript now, instead of just being general `Element` types.
+const combobox = document.querySelector("combobox-field");
+const listbox = document.querySelector("combobox-listbox");
+const options = document.querySelectorAll("combobox-option");
+const selectEnhancer = document.querySelector("select-enhancer");
+```
+
 ### Restyling the Component
 
 For simplicity, the `Combobox` component ships with its own default styles via the `@itenthusiasm/custom-elements/Combobox/Combobox.css` file. You're welcome to use this file directly in your application if you like. However, if you intend to modify _any_ of the styles to fit your own needs, then we recommend creating your own CSS file for the component instead, using our styles as an initial template.

package/README.md

@@ -2,6 +2,18 @@
 
 Robust, accessible, and progressively-enhanceable [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) for common developer needs. Each component integrates seamlessly into your web applications, whether you use pure HTML/CSS/JS or you use a JS Framework.
 
+## Features and Benefits
+
+- **Framework Agnostic**: Because the components in this library are built using only Custom `HTMLElement`s, they work seamlessly in all JS Frameworks (and in pure-JS applications).
+- **Integrates with Native Web Forms**: The components in this library [integrate](https://web.dev/articles/more-capable-form-controls) with the web's native `<form>` element, meaning that their values will be seen in the form's [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and will be automatically [sent to the server](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) when the form is submitted &mdash; all without writing a single line of JS.
+- **Works with Various Form Libraries**: These components emit standard DOM events like [`input`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) and [`change`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event), enabling them to work naturally with reputable form libraries (e.g., the [`Form Observer`](https://github.com/enthusiastic-js/form-observer), [`Conform`](https://conform.guide/), and [`React Hook Form`](https://react-hook-form.com/)).
+- **Progressive Enhacement**: Every form-associated Custom Element in this library progressively enhances the native form controls. This guarantees that your forms will _always_ be fully operable and accessible, even if your users have JS disabled.
+- **Highly Customizable**: These components are flexible enough to work with whatever CSS you provide, and their functionality can be enhanced or overriden through [class extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends).
+- **Performant**: Unlike many other alternatives, these components have been cleverly designed to work without complex state management tools or aggressive DOM Tree manipulation. This makes them fast and memory-efficient.
+- **No Dependencies**: The components in this library are built on the native web platform instead of extending other frameworks or libraries, guaranteeing your bundle size remains as small as possible.
+
+<!-- TODO: Link to article explaining how progressively-enhanced Form Controls _greatly_ simplify frontend code. -->
+
 ## Install
 
 ```
@@ -24,4 +36,13 @@ Below are the components that this library currently provides. Each component ha
       <a href="https://stackblitz.com/edit/custom-elements-combobox?file=index.html,src%2Fmain.ts">Stackblitz Form Integration Demo</a>
     </p>
   </dd>
+
+  <dt id="components-checkbox-group">
+    <a href="./CheckboxGroup"><code>CheckboxGroup</code></a>
+  </dt>
+  <dd>
+    <p>
+      Wraps a semantic group of checkbox <code>&lt;input&gt;</code> elements, progressively enhancing them with convenient features like group-level form validation and value management. The <code>CheckboxGroup</code> component behaves just like the native form controls, meaning that it dispatches the standard <code>input</code>/<code>change</code> events, is <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements">associated</a> with its owning form, and automatically participates in all form activity, <a href="https://web.dev/articles/more-capable-form-controls">including form submission</a>.
+    </p>
+  </dd>
 </dl>

package/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./CheckboxGroup/index.js";
 export * from "./Combobox/index.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1 +1,2 @@
+export * from "./CheckboxGroup/index.js";
 export * from "./Combobox/index.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itenthusiasm/custom-elements",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "sideEffects": false,
   "license": "MIT",
   "description": "Robust, accessible, and progressively-enhanceable Web Components for common developer needs",
@@ -50,6 +50,10 @@
       "types": "./Combobox/index.d.ts",
       "default": "./Combobox/index.js"
     },
+    "./CheckboxGroup": {
+      "types": "./CheckboxGroup/index.d.ts",
+      "default": "./CheckboxGroup/index.js"
+    },
     "./*": {
       "types": "./*.d.ts",
       "default": "./*.js"

package/types/dom.d.ts

@@ -1 +1,2 @@
+import type {} from "../CheckboxGroup/types/dom.d.ts";
 import type {} from "../Combobox/types/dom.d.ts";

package/types/helpers.d.ts

@@ -0,0 +1,12 @@
+// NOTE: For some reason, TS complains in the JS files if we export a `type`, so we're exporting `interface`s instead.
+/* eslint @typescript-eslint/no-empty-object-type: ["error", { "allowInterfaces": "with-single-extends" }] */
+export interface ExposedInternals
+  extends Pick<
+    ElementInternals,
+    "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity"
+  > {}
+
+export interface FieldPropertiesAndMethods
+  extends Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity"> {}
+
+export interface FieldMinMax extends Pick<HTMLInputElement, "min" | "max"> {}

package/types/preact.d.ts

@@ -1 +1,2 @@
+import type {} from "../CheckboxGroup/types/preact.d.ts";
 import type {} from "../Combobox/types/preact.d.ts";

package/types/react.d.ts

@@ -1 +1,2 @@
+import type {} from "../CheckboxGroup/types/react.d.ts";
 import type {} from "../Combobox/types/react.d.ts";

package/types/solid.d.ts

@@ -1 +1,2 @@
+import type {} from "../CheckboxGroup/types/solid.d.ts";
 import type {} from "../Combobox/types/solid.d.ts";

package/types/svelte.d.ts

@@ -1 +1,2 @@
+import type {} from "../CheckboxGroup/types/svelte.d.ts";
 import type {} from "../Combobox/types/svelte.d.ts";

package/types/vue.d.ts

@@ -1 +1,2 @@
+import type {} from "../CheckboxGroup/types/vue.d.ts";
 import type {} from "../Combobox/types/vue.d.ts";