@m3e/form-field 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/NOTICE.md

@@ -0,0 +1,8 @@
+# NOTICE
+
+This package includes code adapted from third-party sources under the MIT license:
+
+- Angular Material Form Field  
+  Source: https://github.com/angular/components  
+  License: MIT  
+  Copyright (c) Google LLC

package/README.md

@@ -0,0 +1,140 @@
+# @m3e/form-field
+
+The `m3e-form-field` component is a semantic, expressive container for form controls that anchors label behavior, subscript messaging, and variant-specific layout. Designed according to Material Design 3 guidelines, it supports two visual variants—`outlined` and `filled`—each with dynamic elevation, shape transitions, and adaptive color theming. The component responds to control state changes (focus, hover, press, disabled, invalid) with smooth motion and semantic clarity, ensuring visual hierarchy and emotional resonance.
+
+> **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/form-field
+```
+
+## 💻 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/form-field`, 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/form-field/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/form-field/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/form-field/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",
+      "@m3e/core/a11y": "/node_modules/@m3e/core/dist/a11y.js"
+    }
+  }
+</script>
+```
+
+> For production, use index.min.js and a11y.min.js for faster load times.
+
+## 🗂️ Elements
+
+- `m3e-form-field` — A container for form controls that applies Material Design styling and behavior.
+
+## 🧪 Examples
+
+The following example illustrates a basic usage of the `m3e-form-field`.
+
+```html
+<m3e-form-field>
+  <label slot="label" for="field">Text field</label>
+  <input id="field" />
+</m3e-form-field>
+```
+
+## 📖 API Reference
+
+This section details the attributes, slots and CSS custom properties available for the `m3e-form-field` component.
+
+### ⚙️ Attributes
+
+| Attribute              | Type                                | Default      | Description                                                             |
+| ---------------------- | ----------------------------------- | ------------ | ----------------------------------------------------------------------- |
+| `variant`              | `"filled"` \| `"outlined"`          | `"outlined"` | The appearance variant of the field.                                    |
+| `hide-required-marker` | `boolean`                           | `false`      | Whether the required marker should be hidden.                           |
+| `hide-subscript`       | `"always"` \| `"auto"` \| `"never"` | `"auto"`     | Whether subscript content is hidden.                                    |
+| `float-label`          | `"always"` \| `"auto"`              | `"auto"`     | Specifies whether the label should float always or only when necessary. |
+
+### 🧩 Slots
+
+| Slot          | Description                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| _(default)_   | Renders the form control (e.g. `<input>`, `<select>`, or custom control).   |
+| `prefix`      | Renders visual content before the control (e.g. icons, avatars, tokens).    |
+| `prefix-text` | Renders plain text before the control, aligned with the input baseline.     |
+| `suffix`      | Renders visual content after the control (e.g. icons, buttons, indicators). |
+| `suffix-text` | Renders plain text after the control, aligned with the input baseline.      |
+| `hint`        | Renders hint text in the subscript area when the control is valid.          |
+| `error`       | Renders error text in the subscript area when the control is invalid.       |
+
+#### 🧠 Notes
+
+- Only one control should be slotted at a time.
+- `hint` and `error` slots are mutually exclusive based on control validity.
+- Prefix/suffix slots support both decorative and interactive content.
+- Floating label behavior is automatically coordinated with control state and value.
+
+### 🎛️ CSS Custom Properties
+
+| Property                                      | Description                                       |
+| --------------------------------------------- | ------------------------------------------------- |
+| `--m3e-form-field-font-size`                  | Font size for the form field container text.      |
+| `--m3e-form-field-font-weight`                | Font weight for the form field container text.    |
+| `--m3e-form-field-line-height`                | Line height for the form field container text.    |
+| `--m3e-form-field-tracking`                   | Letter spacing for the form field container text. |
+| `--m3e-form-field-label-font-size`            | Font size for the floating label.                 |
+| `--m3e-form-field-label-font-weight`          | Font weight for the floating label.               |
+| `--m3e-form-field-label-line-height`          | Line height for the floating label.               |
+| `--m3e-form-field-label-tracking`             | Letter spacing for the floating label.            |
+| `--m3e-form-field-subscript-font-size`        | Font size for hint and error text.                |
+| `--m3e-form-field-subscript-font-weight`      | Font weight for hint and error text.              |
+| `--m3e-form-field-subscript-line-height`      | Line height for hint and error text.              |
+| `--m3e-form-field-subscript-tracking`         | Letter spacing for hint and error text.           |
+| `--m3e-form-field-color`                      | Text color for the form field container.          |
+| `--m3e-form-field-subscript-color`            | Color for hint and error text.                    |
+| `--m3e-form-field-invalid-color`              | Color used when the control is invalid.           |
+| `--m3e-form-field-focused-outline-color`      | Outline color when focused.                       |
+| `--m3e-form-field-focused-color`              | Label color when focused.                         |
+| `--m3e-form-field-outline-color`              | Outline color in outlined variant.                |
+| `--m3e-form-field-container-color`            | Background color in filled variant.               |
+| `--m3e-form-field-hover-container-color`      | Hover background color in filled variant.         |
+| `--m3e-form-field-width`                      | Width of the form field container.                |
+| `--m3e-form-field-icon-size`                  | Size of prefix and suffix icons.                  |
+| `--m3e-outlined-form-field-container-shape`   | Corner radius for outlined container.             |
+| `--m3e-form-field-container-shape`            | Corner radius for filled container.               |
+| `--m3e-form-field-hover-container-opacity`    | Opacity for hover background in filled variant.   |
+| `--m3e-form-field-disabled-opacity`           | Opacity for disabled text.                        |
+| `--m3e-form-field-disabled-container-opacity` | Opacity for disabled container background.        |
+
+## 🤝 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,116 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Form Field for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Form Field 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",
+          "@m3e/core/a11y": "../../core/dist/a11y.min.js"
+        }
+      }
+    </script>
+    <script type="module" src="../../icon/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>
+      <m3e-form-field variant="outlined">
+        <label slot="label" for="fld1">Outlined Field</label>
+        <input autocomplete="off" id="fld1" />
+      </m3e-form-field>
+      <br />
+      <m3e-form-field variant="filled">
+        <label slot="label" for="fld2">Filled Field</label>
+        <input autocomplete="off" id="fld2" />
+      </m3e-form-field>
+      <br />
+      <m3e-form-field float-label="always">
+        <label slot="label" for="fld3">Always float label</label>
+        <input autocomplete="off" id="fld3" />
+      </m3e-form-field>
+      <br />
+      <m3e-form-field>
+        <label slot="label" for="fld4">With hint text (auto)</label>
+        <input autocomplete="off" id="fld4" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <br />
+      <m3e-form-field>
+        <label slot="label" for="fld5">Hide subscript auto</label>
+        <input autocomplete="off" id="fld5" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <br />
+      <m3e-form-field hide-subscript="never">
+        <label slot="label" for="fld6">Hide subscript never</label>
+        <input autocomplete="off" id="fld6" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <br /><br />
+      <m3e-form-field hide-subscript="always">
+        <label slot="label" for="fld7">Hide subscript always</label>
+        <input autocomplete="off" id="fld7" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <br /><br />
+      <m3e-form-field style="--md-sys-density-scale: -1">
+        <label slot="label" for="fld8">Outlined comfortable density</label>
+        <input autocomplete="off" id="fld8" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <m3e-form-field variant="filled" style="--md-sys-density-scale: -1">
+        <label slot="label" for="fld9">Filled comfortable density</label>
+        <input autocomplete="off" id="fld9" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <br />
+      <m3e-form-field style="--md-sys-density-scale: -2">
+        <label slot="label" for="fld10">Outlined compact density</label>
+        <input autocomplete="off" id="fld10" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <m3e-form-field variant="filled" style="--md-sys-density-scale: -2">
+        <label slot="label" for="fld11">Filled compact density</label>
+        <input autocomplete="off" id="fld11" />
+        <span slot="hint">Hint text</span>
+      </m3e-form-field>
+      <br /><br />
+      <m3e-form-field>
+        <label slot="label" for="fld12">Required field</label>
+        <input required autocomplete="off" id="fld12" />
+        <span slot="hint">Required</span>
+      </m3e-form-field>
+      <br /><br />
+      <m3e-form-field>
+        <label slot="label" for="fld13">Disabled field</label>
+        <input disabled autocomplete="off" id="fld13" value="Sample value" />
+        <span slot="hint">Disabled</span>
+      </m3e-form-field>
+    </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-form-field-font-size",
+      "description": "Font size for the form field container text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-font-weight",
+      "description": "Font weight for the form field container text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-line-height",
+      "description": "Line height for the form field container text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-tracking",
+      "description": "Letter spacing for the form field container text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-label-font-size",
+      "description": "Font size for the floating label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-label-font-weight",
+      "description": "Font weight for the floating label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-label-line-height",
+      "description": "Line height for the floating label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-label-tracking",
+      "description": "Letter spacing for the floating label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-subscript-font-size",
+      "description": "Font size for hint and error text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-subscript-font-weight",
+      "description": "Font weight for hint and error text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-subscript-line-height",
+      "description": "Line height for hint and error text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-subscript-tracking",
+      "description": "Letter spacing for hint and error text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-color",
+      "description": "Text color for the form field container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-subscript-color",
+      "description": "Color for hint and error text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-invalid-color",
+      "description": "Color used when the control is invalid.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-focused-outline-color",
+      "description": "Outline color when focused.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-focused-color",
+      "description": "Label color when focused.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-outline-color",
+      "description": "Outline color in outlined variant.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-container-color",
+      "description": "Background color in filled variant.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-hover-container-color",
+      "description": "Hover background color in filled variant.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-width",
+      "description": "Width of the form field container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-icon-size",
+      "description": "Size of prefix and suffix icons.",
+      "values": []
+    },
+    {
+      "name": "--m3e-outlined-form-field-container-shape",
+      "description": "Corner radius for outlined container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-container-shape",
+      "description": "Corner radius for filled container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-hover-container-opacity",
+      "description": "Opacity for hover background in filled variant.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-disabled-opacity",
+      "description": "Opacity for disabled text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-form-field-disabled-container-opacity",
+      "description": "Opacity for disabled container background.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}