@m3e/fab 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,181 @@
+# @m3e/fab
+
+The `m3e-fab` component is a prominent, expressive UI component that represents the primary action on a screen. Designed according to Material Design 3 guidelines, it supports seven visual variants, specified using the `variant` attribute—`primary`, `primary-container`, `secondary`, `secondary-container`, `tertiary`, `tertiary-container` and `surface`—each with dynamic elevation and adaptive color theming.
+
+The component is accessible by default, with ARIA roles, contrast-safe color tokens, and strong focus indicators. It can be extended to display a label alongside its icon, and responds to interaction states (hover, focus, press, disabled) with smooth motion transitions, elevation changes, and adaptive color theming. It can also function as a link or be used to submit form data.
+
+Native disabled `<button>` elements cannot receive focus. This can be problematic in some cases because it can prevent you from telling the user why the button is disabled. You can use the `disabled-interactive` attribute to style a `m3e-fab` as disabled but allow for it to receive focus. The button will have `aria-disabled="true"` for assistive technology.
+
+> **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/fab
+```
+
+## 💻 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/fab`, 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/fab/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/fab/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/fab/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-fab` — A floating action button (FAB) used to present important actions.
+
+## 🧪 Examples
+
+The following example illustrates a basic floating action button.
+
+```html
+<m3e-fab>
+  <m3e-icon>add</m3e-icon>
+</m3e-fab>
+```
+
+The next example illustrates an extended floating action button.
+
+```html
+<m3e-fab extended>
+  <m3e-icon>add</m3e-icon>
+  <span slot="label">Add</span>
+</m3e-fab>
+```
+
+## 📖 API Reference
+
+This section details the attributes, slots and CSS custom properties available for the `m3e-fab` component.
+
+### ⚙️ Attributes
+
+| Attribute              | Type                                                                                                                          | Default               | Description                                                                                                                            |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`              | `"primary" \| "primary-container" \| "secondary" \| "secondary-container" \| "tertiary" \| "tertiary-container" \| "surface"` | `"primary-container"` | The appearance variant of the FAB.                                                                                                     |
+| `size`                 | `"small" \| "medium" \| "large"`                                                                                              | `"medium"`            | The size of the FAB.                                                                                                                   |
+| `extended`             | `boolean`                                                                                                                     | `false`               | Whether the FAB is extended to show the label.                                                                                         |
+| `lowered`              | `boolean`                                                                                                                     | `false`               | Whether to present a lowered elevation.                                                                                                |
+| `disabled`             | `boolean`                                                                                                                     | `false`               | Whether the element is disabled.                                                                                                       |
+| `disabled-interactive` | `boolean`                                                                                                                     | `false`               | Whether the element is disabled and interactive.                                                                                       |
+| `type`                 | `"button" \| "submit" \| "reset"`                                                                                             | `"button"`            | The type of the element.                                                                                                               |
+| `name`                 | `string`                                                                                                                      |                       | The name of the element, submitted as a pair with the element's value as part of form data, when the element is used to submit a form. |
+| `value`                | `string`                                                                                                                      |                       | The value associated with the element's name when it's submitted with form data.                                                       |
+| `href`                 | `string`                                                                                                                      |                       | The URL to which the link FAB points.                                                                                                  |
+| `target`               | `string`                                                                                                                      |                       | The target of the link FAB.                                                                                                            |
+| `rel`                  | `string`                                                                                                                      |                       | The relationship between the target of the link FAB and the document.                                                                  |
+| `download`             | `string`                                                                                                                      |                       | A value indicating whether the target of the link FAB will be downloaded, optionally specifying the new name of the file.              |
+
+### 🧩 Slots
+
+| Slot         | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| _(default)_  | Renders the icon of the button.                      |
+| `label`      | Renders the label of an extended FAB.                |
+| `close-icon` | Renders the close icon when used to open a FAB menu. |
+
+### 🎛️ CSS Custom Properties
+
+#### 🧱 Size Properties
+
+All size variants (`small`, `medium`, `large`) support:
+
+| Property                                  | Description                  |
+| ----------------------------------------- | ---------------------------- |
+| `--m3e-fab-[size]-container-height`       | Height of the FAB container  |
+| `--m3e-fab-[size]-label-text-font-size`   | Font size for label          |
+| `--m3e-fab-[size]-label-text-font-weight` | Font weight for label        |
+| `--m3e-fab-[size]-label-text-line-height` | Line height for label        |
+| `--m3e-fab-[size]-label-text-tracking`    | Letter tracking for label    |
+| `--m3e-fab-[size]-icon-size`              | Icon size                    |
+| `--m3e-fab-[size]-shape`                  | Corner radius                |
+| `--m3e-fab-[size]-leading-space`          | Space before icon/label      |
+| `--m3e-fab-[size]-trailing-space`         | Space after icon/label       |
+| `--m3e-fab-[size]-icon-label-space`       | Space between icon and label |
+
+#### 🎨 Appearance Variant Properties
+
+All appearance variants (`primary`, `primary-container`, `secondary`, `secondary-container`, `tertiary`, `tertiary-container`, `surface`) support:
+
+| Property                                          | Description                |
+| ------------------------------------------------- | -------------------------- |
+| `--m3e-[variant]-fab-label-text-color`            | Label color                |
+| `--m3e-[variant]-fab-icon-color`                  | Icon color                 |
+| `--m3e-[variant]-fab-container-color`             | Container background color |
+| `--m3e-[variant]-fab-container-elevation`         | Elevation                  |
+| `--m3e-[variant]-fab-lowered-container-elevation` | Lowered elevation          |
+
+#### 🟫 State Properties
+
+Each variant supports state properties for disabled, hover, focus, and pressed. For each variant, the following properties are available (replace `[variant]` with the variant name):
+
+| Property                                                   | Description                     |
+| ---------------------------------------------------------- | ------------------------------- |
+| `--m3e-[variant]-fab-disabled-label-text-color`            | Label color when disabled       |
+| `--m3e-[variant]-fab-disabled-label-text-opacity`          | Label opacity when disabled     |
+| `--m3e-[variant]-fab-disabled-icon-color`                  | Icon color when disabled        |
+| `--m3e-[variant]-fab-disabled-icon-opacity`                | Icon opacity when disabled      |
+| `--m3e-[variant]-fab-disabled-container-color`             | Container color when disabled   |
+| `--m3e-[variant]-fab-disabled-container-opacity`           | Container opacity when disabled |
+| `--m3e-[variant]-fab-disabled-container-elevation`         | Elevation when disabled         |
+| `--m3e-[variant]-fab-lowered-disabled-container-elevation` | Lowered elevation when disabled |
+| `--m3e-[variant]-fab-hover-label-text-color`               | Label color on hover            |
+| `--m3e-[variant]-fab-hover-icon-color`                     | Icon color on hover             |
+| `--m3e-[variant]-fab-hover-state-layer-color`              | State layer color on hover      |
+| `--m3e-[variant]-fab-hover-state-layer-opacity`            | State layer opacity on hover    |
+| `--m3e-[variant]-fab-hover-container-elevation`            | Elevation on hover              |
+| `--m3e-[variant]-fab-lowered-hover-container-elevation`    | Lowered elevation on hover      |
+| `--m3e-[variant]-fab-focus-label-text-color`               | Label color on focus            |
+| `--m3e-[variant]-fab-focus-icon-color`                     | Icon color on focus             |
+| `--m3e-[variant]-fab-focus-state-layer-color`              | State layer color on focus      |
+| `--m3e-[variant]-fab-focus-state-layer-opacity`            | State layer opacity on focus    |
+| `--m3e-[variant]-fab-focus-container-elevation`            | Elevation on focus              |
+| `--m3e-[variant]-fab-lowered-focus-container-elevation`    | Lowered elevation on focus      |
+| `--m3e-[variant]-fab-pressed-label-text-color`             | Label color on press            |
+| `--m3e-[variant]-fab-pressed-icon-color`                   | Icon color on press             |
+| `--m3e-[variant]-fab-pressed-state-layer-color`            | State layer color on press      |
+| `--m3e-[variant]-fab-pressed-state-layer-opacity`          | State layer opacity on press    |
+| `--m3e-[variant]-fab-pressed-container-elevation`          | Elevation on press              |
+| `--m3e-[variant]-fab-lowered-pressed-container-elevation`  | Lowered elevation on press      |
+
+## 🤝 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,80 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Floating Action Button for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Floating Action Button 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="../../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-fab aria-label="Fab" variant="primary-container"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" variant="secondary-container"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" variant="tertiary-container"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" variant="primary"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" variant="secondary"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" variant="tertiary"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" variant="surface"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <br /><br />
+
+      <m3e-fab size="small"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab size="medium"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab size="large"><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <br /><br />
+
+      <m3e-fab>
+        <m3e-icon name="edit"></m3e-icon>
+        <span slot="label">Extended</span>
+      </m3e-fab>
+      <m3e-fab extended>
+        <span slot="label">Extended</span>
+      </m3e-fab>
+      <br /><br />
+
+      <m3e-fab href="https://m3.material.io/components/floating-action-button/overview" target="_blank" extended>
+        <m3e-icon name="edit"></m3e-icon>
+        <span slot="label">Link Button</span>
+      </m3e-fab>
+      <m3e-fab
+        href="https://m3.material.io/components/floating-action-button/overview"
+        target="_blank"
+        aria-label="Fab"
+      >
+        <m3e-icon name="edit"></m3e-icon>
+      </m3e-fab>
+      <br /><br />
+      <m3e-fab aria-label="Fab" disabled><m3e-icon name="edit"></m3e-icon></m3e-fab>
+      <m3e-fab aria-label="Fab" disabled-interactive><m3e-icon name="edit"></m3e-icon></m3e-fab>
+    </m3e-theme>
+  </body>
+</html>