@m3e/checkbox 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 matraic
+Contact: matraic@yahoo.com
+
+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,135 @@
+# @m3e/checkbox
+
+The `m3e-checkbox` component enables users to select one or more options from a set. It supports selected, unselected, and indeterminate states, and communicates selection through visual cues and accessible semantics. This component reflects user intent, form participation, and validation feedback, adapting to disabled and required contexts. It emits `input` and `change` events to signal state transitions and integrates with form submission via `name` and `value`.
+
+> **Part of the [M3E](../../README.md) monorepo**  
+> This package is maintained within the unified M3E repository, which provides a suite of Material 3 web components.
+
+## 📦 Installation
+
+```bash
+npm install @m3e/checkbox
+```
+
+## 💻 Editor Integration
+
+This package includes a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) to support enhanced editor tooling and developer experience.
+
+### Visual Studio Code
+
+To enable autocomplete and hover documentation for `@m3e/checkbox`, install the [Custom Elements Manifest Language Server](https://marketplace.visualstudio.com/items?itemName=pwrs.cem-language-server-vscode) extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.
+
+Alternately, you can explicitly reference the `html-custom-data.json` and `css-custom-data.json` in your workspace settings:
+
+```json
+{
+  "html.customData": ["./node_modules/@m3e/checkbox/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/checkbox/dist/css-custom-data.json"]
+}
+```
+
+## 🚀 Browser Usage
+
+This package uses [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#module_specifiers). To use it directly in a browser without a bundler, use a module script similar to the following.
+
+```html
+<script type="module" src="/node_modules/@m3e/checkbox/dist/index.js"></script>
+```
+
+In addition, you must use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) to include dependencies.
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
+      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
+    }
+  }
+</script>
+```
+
+> For production, use index.min.js for faster load times.
+
+## 🗂️ Elements
+
+- `m3e-checkbox` — A checkbox that allows a user to select one or more options from a limited number of choices.
+
+## 🧪 Examples
+
+The following example illustrates wrapping a `m3e-checkbox` within a `label`.
+
+```html
+<label>
+  <m3e-checkbox></m3e-checkbox>
+  Checkbox label
+</label>
+```
+
+The next example illustrates use of the `for` attribute to label a checkbox.
+
+```html
+<m3e-checkbox id="chk"></m3e-checkbox><label for="chk">Checkbox label </label>
+```
+
+## 📖 API Reference
+
+This section details the attributes, events and CSS custom properties available for the `m3e-checkbox` component.
+
+### ⚙️ Attributes
+
+| Attribute       | Type      | Default | Description                                                               |
+| --------------- | --------- | ------- | ------------------------------------------------------------------------- |
+| `checked`       | `boolean` | `false` | Whether the element is checked.                                           |
+| `disabled`      | `boolean` | `false` | Whether the element is disabled.                                          |
+| `indeterminate` | `boolean` | `false` | Whether the element's checked state is indeterminate.                     |
+| `name`          | `string`  |         | The name that identifies the element when submitting the associated form. |
+| `required`      | `boolean` | `false` | Whether the element is required.                                          |
+| `value`         | `string`  | `"on"`  | A string representing the value of the checkbox.                          |
+
+#### 🔔 Events
+
+| Event    | Description                             |
+| -------- | --------------------------------------- |
+| `input`  | Emitted when the checked state changes. |
+| `change` | Emitted when the checked state changes. |
+
+### 🎛️ CSS Custom Properties
+
+| Property                                             | Description                                      |
+| ---------------------------------------------------- | ------------------------------------------------ |
+| `--m3e-checkbox-icon-size`                           | Size of the checkbox icon inside the container.  |
+| `--m3e-checkbox-container-size`                      | Base size of the checkbox container.             |
+| `--m3e-checkbox-container-shape`                     | Border radius of the icon container.             |
+| `--m3e-checkbox-unselected-outline-thickness`        | Border thickness for unselected state.           |
+| `--m3e-checkbox-unselected-outline-color`            | Border color for unselected state.               |
+| `--m3e-checkbox-unselected-hover-outline-color`      | Border color on hover when unselected.           |
+| `--m3e-checkbox-unselected-disabled-outline-color`   | Base color for disabled unselected outline.      |
+| `--m3e-checkbox-unselected-disabled-outline-opacity` | Opacity for disabled unselected outline.         |
+| `--m3e-checkbox-unselected-error-outline-color`      | Border color for invalid unselected state.       |
+| `--m3e-checkbox-selected-container-color`            | Background color for selected container.         |
+| `--m3e-checkbox-selected-icon-color`                 | Icon color for selected state.                   |
+| `--m3e-checkbox-selected-disabled-container-color`   | Base color for disabled selected container.      |
+| `--m3e-checkbox-selected-disabled-container-opacity` | Opacity for disabled selected container.         |
+| `--m3e-checkbox-selected-disabled-icon-color`        | Base color for disabled selected icon.           |
+| `--m3e-checkbox-selected-disabled-icon-opacity`      | Opacity for disabled selected icon.              |
+| `--m3e-checkbox-unselected-hover-color`              | Ripple hover color for unselected state.         |
+| `--m3e-checkbox-unselected-focus-color`              | Ripple focus color for unselected state.         |
+| `--m3e-checkbox-unselected-ripple-color`             | Ripple base color for unselected state.          |
+| `--m3e-checkbox-selected-hover-color`                | Ripple hover color for selected state.           |
+| `--m3e-checkbox-selected-focus-color`                | Ripple focus color for selected state.           |
+| `--m3e-checkbox-selected-ripple-color`               | Ripple base color for selected state.            |
+| `--m3e-checkbox-unselected-error-hover-color`        | Ripple hover color for invalid unselected state. |
+| `--m3e-checkbox-unselected-error-focus-color`        | Ripple focus color for invalid unselected state. |
+| `--m3e-checkbox-unselected-error-ripple-color`       | Ripple base color for invalid unselected state.  |
+| `--m3e-checkbox-selected-error-hover-color`          | Ripple hover color for invalid selected state.   |
+| `--m3e-checkbox-selected-error-focus-color`          | Ripple focus color for invalid selected state.   |
+| `--m3e-checkbox-selected-error-ripple-color`         | Ripple base color for invalid selected state.    |
+
+## 🤝 Contributing
+
+See the root monorepo `CONTRIBUTING.md` for guidelines on contributing to this package.
+
+## 📄 License
+
+This package is licensed under the MIT License.

package/cem.config.mjs

@@ -0,0 +1,16 @@
+import { customElementVsCodePlugin } from "custom-element-vs-code-integration";
+
+export default {
+  globs: ["src/**/*.ts"],
+  exclude: ["src/**/*.spec.ts"],
+  packagejson: true,
+  outdir: "dist",
+  litelement: true,
+  plugins: [
+    customElementVsCodePlugin({
+      outdir: "dist",
+      htmlFileName: "html-custom-data.json",
+      cssFileName: "css-custom-data.json",
+    }),
+  ],
+};

package/demo/index.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Checkbox for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Checkbox for M3E" />
+    <base href="./" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap"
+      rel="stylesheet"
+    />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0..1,0"
+      rel="stylesheet"
+    />
+    <script type="importmap">
+      {
+        "imports": {
+          "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
+          "@m3e/core": "../../core/dist/index.min.js"
+        }
+      }
+    </script>
+    <script type="module" src="../../theme/dist/index.min.js"></script>
+    <script type="module" src="../dist/index.min.js"></script>
+    <style>
+      body {
+        font-family: "Roboto";
+      }
+      *:not(:defined) {
+        display: none;
+      }
+    </style>
+  </head>
+  <body>
+    <m3e-theme strong-focus>
+      <label>
+        <m3e-checkbox></m3e-checkbox>
+        Checkbox label
+      </label>
+      <br />
+      <m3e-checkbox id="chk"></m3e-checkbox>
+      <label for="chk">Checkbox label </label>
+      <br />
+      <label>
+        <m3e-checkbox indeterminate></m3e-checkbox>
+        Indeterminate checkbox
+      </label>
+      <br />
+      <label>
+        <m3e-checkbox required></m3e-checkbox>
+        Required checkbox
+      </label>
+      <br />
+      <label>
+        <m3e-checkbox disabled></m3e-checkbox>
+        Disabled checkbox
+      </label>
+      <br />
+      <label>
+        <m3e-checkbox disabled checked></m3e-checkbox>
+        Disabled checked checkbox
+      </label>
+      <br />
+      <label>
+        <m3e-checkbox disabled indeterminate></m3e-checkbox>
+        Disabled indeterminate checkbox
+      </label>
+    </m3e-theme>
+  </body>
+</html>

package/dist/css-custom-data.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-checkbox-icon-size",
+      "description": "Size of the checkbox icon inside the container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-container-size",
+      "description": "Base size of the checkbox container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-container-shape",
+      "description": "Border radius of the icon container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-outline-thickness",
+      "description": "Border thickness for unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-outline-color",
+      "description": "Border color for unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-hover-outline-color",
+      "description": "Border color on hover when unselected.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-disabled-outline-color",
+      "description": "Base color for disabled unselected outline.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-disabled-outline-opacity",
+      "description": "Opacity for disabled unselected outline.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-error-outline-color",
+      "description": "Border color for invalid unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-container-color",
+      "description": "Background color for selected container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-icon-color",
+      "description": "Icon color for selected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-disabled-container-color",
+      "description": "Base color for disabled selected container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-disabled-container-opacity",
+      "description": "Opacity for disabled selected container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-disabled-icon-color",
+      "description": "Base color for disabled selected icon.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-disabled-icon-opacity",
+      "description": "Opacity for disabled selected icon.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-hover-color",
+      "description": "Ripple hover color for unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-focus-color",
+      "description": "Ripple focus color for unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-ripple-color",
+      "description": "Ripple base color for unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-hover-color",
+      "description": "Ripple hover color for selected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-focus-color",
+      "description": "Ripple focus color for selected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-ripple-color",
+      "description": "Ripple base color for selected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-error-hover-color",
+      "description": "Ripple hover color for invalid unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-error-focus-color",
+      "description": "Ripple focus color for invalid unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-unselected-error-ripple-color",
+      "description": "Ripple base color for invalid unselected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-error-hover-color",
+      "description": "Ripple hover color for invalid selected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-error-focus-color",
+      "description": "Ripple focus color for invalid selected state.",
+      "values": []
+    },
+    {
+      "name": "--m3e-checkbox-selected-error-ripple-color",
+      "description": "Ripple base color for invalid selected state.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}