@m3e/card 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,268 @@
+# @m3e/card
+
+The `m3e-card` component is a flexible, expressive container for presenting a unified subject—text, media, and actions—on a visually distinct surface. It supports multiple appearance variants via the `variant` attribute: `filled` (default, for solid emphasis), `outlined` (for subtle framing with a border), and `elevated` (for depth and motion with shadow elevation).
+
+Cards can be made actionable, responding to user interaction when the `actionable` attribute is set, and can be presented inline with surrounding content using the `inline` attribute.
+
+It supports both vertical and horizontal layouts through the `orientation` attribute. Content organization is enabled via dedicated slots for `header`, `content`, `actions`, and `footer`, or developers can use the default slot for custom layouts.
+
+The component provides dynamic elevation, adaptive shape, and expressive color theming, and responds to interaction states (hover, focus, press, disabled) with smooth motion and visual feedback, ensuring clarity, accessibility, and a cohesive user experience in accordance with Material Design 3 guidelines.
+
+> **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/card
+```
+
+## 💻 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/card`, 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/card/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/card/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/card/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-card` — A content container for text, images (or other media), and actions in the context of a single subject.
+
+## 🧪 Examples
+
+The following example illustrates each of the dedicated slots of a card.
+
+```html
+<m3e-card>
+  <div slot="header">Header section</div>
+  <div slot="content">Content section</div>
+  <div slot="actions">Actions section</div>
+  <div slot="footer">Footer section</div>
+</m3e-card>
+```
+
+## 📖 API Reference
+
+This section details the attributes, slots and CSS custom properties available for the `m3e-card` component.
+
+### ⚙️ Attributes
+
+| Attribute     | Type                                   | Default      | Description                                                           |
+| ------------- | -------------------------------------- | ------------ | --------------------------------------------------------------------- |
+| `actionable`  | `boolean`                              | `false`      | Whether the card is "actionable" and will respond to use interaction. |
+| `inline`      | `boolean`                              | `false`      | Whether to present the card inline with surrounding content.          |
+| `orientation` | `"horizontal" \| "vertical"`           | `"vertical"` | The orientation of the card.                                          |
+| `variant`     | `"filled" \| "outlined" \| "elevated"` | `"filled"`   | The appearance variant of the card.                                   |
+
+### 🧩 Slots
+
+| Slot        | Description                      |
+| ----------- | -------------------------------- |
+| _(default)_ | Renders content without padding. |
+| `header`    | Renders the header section.      |
+| `content`   | Renders padded content.          |
+| `actions`   | Renders interactive controls.    |
+| `footer`    | Renders footer content.          |
+
+### 🎛️ CSS Custom Properties
+
+The `m3e-card` element supports extensive theming via scoped CSS custom properties. These properties enable fine-grained control over layout, shape, elevation, color, and interaction states across all appearance variants.
+
+#### 🧱 Global Properties
+
+| Property             | Description                               |
+| -------------------- | ----------------------------------------- |
+| `--m3e-card-padding` | Internal spacing for all slotted regions. |
+| `--m3e-card-shape`   | Corner radius of the card container.      |
+
+#### 🟫 Filled Variant
+
+##### Base
+
+| Property                                | Description                        |
+| --------------------------------------- | ---------------------------------- |
+| `--m3e-filled-card-text-color`          | Foreground color for text content. |
+| `--m3e-filled-card-container-color`     | Background color of the container. |
+| `--m3e-filled-card-container-elevation` | Elevation level of the container.  |
+
+##### Disabled
+
+| Property                                                 | Description                              |
+| -------------------------------------------------------- | ---------------------------------------- |
+| `--m3e-filled-card-disabled-text-color`                  | Text color when disabled.                |
+| `--m3e-filled-card-disabled-text-opacity`                | Opacity applied to text when disabled.   |
+| `--m3e-filled-card-disabled-container-color`             | Background color when disabled.          |
+| `--m3e-filled-card-disabled-container-elevation`         | Elevation level when disabled.           |
+| `--m3e-filled-card-disabled-container-elevation-color`   | Shadow color when disabled.              |
+| `--m3e-filled-card-disabled-container-elevation-opacity` | Shadow opacity when disabled.            |
+| `--m3e-filled-card-disabled-container-opacity`           | Overall container opacity when disabled. |
+
+##### Hover
+
+| Property                                      | Description                   |
+| --------------------------------------------- | ----------------------------- |
+| `--m3e-filled-card-hover-text-color`          | Text color on hover.          |
+| `--m3e-filled-card-hover-state-layer-color`   | State layer color on hover.   |
+| `--m3e-filled-card-hover-state-layer-opacity` | State layer opacity on hover. |
+| `--m3e-filled-card-hover-container-elevation` | Elevation level on hover.     |
+
+##### Focus
+
+| Property                                      | Description                   |
+| --------------------------------------------- | ----------------------------- |
+| `--m3e-filled-card-focus-text-color`          | Text color on focus.          |
+| `--m3e-filled-card-focus-state-layer-color`   | State layer color on focus.   |
+| `--m3e-filled-card-focus-state-layer-opacity` | State layer opacity on focus. |
+| `--m3e-filled-card-focus-container-elevation` | Elevation level on focus.     |
+
+##### Pressed
+
+| Property                                        | Description                   |
+| ----------------------------------------------- | ----------------------------- |
+| `--m3e-filled-card-pressed-text-color`          | Text color on press.          |
+| `--m3e-filled-card-pressed-state-layer-color`   | State layer color on press.   |
+| `--m3e-filled-card-pressed-state-layer-opacity` | State layer opacity on press. |
+| `--m3e-filled-card-pressed-container-elevation` | Elevation level on press.     |
+
+#### 🟪 Elevated Variant
+
+##### Base
+
+| Property                                  | Description                        |
+| ----------------------------------------- | ---------------------------------- |
+| `--m3e-elevated-card-text-color`          | Foreground color for text content. |
+| `--m3e-elevated-card-container-color`     | Background color of the container. |
+| `--m3e-elevated-card-container-elevation` | Elevation level of the container.  |
+
+##### Disabled
+
+| Property                                                   | Description                              |
+| ---------------------------------------------------------- | ---------------------------------------- |
+| `--m3e-elevated-card-disabled-text-color`                  | Text color when disabled.                |
+| `--m3e-elevated-card-disabled-text-opacity`                | Opacity applied to text when disabled.   |
+| `--m3e-elevated-card-disabled-container-color`             | Background color when disabled.          |
+| `--m3e-elevated-card-disabled-container-elevation`         | Elevation level when disabled.           |
+| `--m3e-elevated-card-disabled-container-elevation-color`   | Shadow color when disabled.              |
+| `--m3e-elevated-card-disabled-container-elevation-opacity` | Shadow opacity when disabled.            |
+| `--m3e-elevated-card-disabled-container-opacity`           | Overall container opacity when disabled. |
+
+##### Hover
+
+| Property                                        | Description                   |
+| ----------------------------------------------- | ----------------------------- |
+| `--m3e-elevated-card-hover-text-color`          | Text color on hover.          |
+| `--m3e-elevated-card-hover-state-layer-color`   | State layer color on hover.   |
+| `--m3e-elevated-card-hover-state-layer-opacity` | State layer opacity on hover. |
+| `--m3e-elevated-card-hover-container-elevation` | Elevation level on hover.     |
+
+##### Focus
+
+| Property                                        | Description                   |
+| ----------------------------------------------- | ----------------------------- |
+| `--m3e-elevated-card-focus-text-color`          | Text color on focus.          |
+| `--m3e-elevated-card-focus-state-layer-color`   | State layer color on focus.   |
+| `--m3e-elevated-card-focus-state-layer-opacity` | State layer opacity on focus. |
+| `--m3e-elevated-card-focus-container-elevation` | Elevation level on focus.     |
+
+##### Pressed
+
+| Property                                          | Description                   |
+| ------------------------------------------------- | ----------------------------- |
+| `--m3e-elevated-card-pressed-text-color`          | Text color on press.          |
+| `--m3e-elevated-card-pressed-state-layer-color`   | State layer color on press.   |
+| `--m3e-elevated-card-pressed-state-layer-opacity` | State layer opacity on press. |
+| `--m3e-elevated-card-pressed-container-elevation` | Elevation level on press.     |
+
+#### 🟦 Outlined Variant
+
+##### Base
+
+| Property                                  | Description                        |
+| ----------------------------------------- | ---------------------------------- |
+| `--m3e-outlined-card-text-color`          | Foreground color for text content. |
+| `--m3e-outlined-card-container-elevation` | Elevation level of the container.  |
+| `--m3e-outlined-card-outline-color`       | Border color of the card.          |
+| `--m3e-outlined-card-outline-thickness`   | Border thickness of the card.      |
+
+##### Disabled
+
+| Property                                                   | Description                            |
+| ---------------------------------------------------------- | -------------------------------------- |
+| `--m3e-outlined-card-disabled-text-color`                  | Text color when disabled.              |
+| `--m3e-outlined-card-disabled-text-opacity`                | Opacity applied to text when disabled. |
+| `--m3e-outlined-card-disabled-container-elevation`         | Elevation level when disabled.         |
+| `--m3e-outlined-card-disabled-container-elevation-color`   | Shadow color when disabled.            |
+| `--m3e-outlined-card-disabled-container-elevation-opacity` | Shadow opacity when disabled.          |
+| `--m3e-outlined-card-disabled-outline-color`               | Border color when disabled.            |
+| `--m3e-outlined-card-disabled-outline-opacity`             | Border opacity when disabled.          |
+
+##### Hover
+
+| Property                                        | Description                   |
+| ----------------------------------------------- | ----------------------------- |
+| `--m3e-outlined-card-hover-text-color`          | Text color on hover.          |
+| `--m3e-outlined-card-hover-state-layer-color`   | State layer color on hover.   |
+| `--m3e-outlined-card-hover-state-layer-opacity` | State layer opacity on hover. |
+| `--m3e-outlined-card-hover-container-elevation` | Elevation level on hover.     |
+| `--m3e-outlined-card-hover-outline-color`       | Border color on hover.        |
+
+##### Focus
+
+| Property                                        | Description                   |
+| ----------------------------------------------- | ----------------------------- |
+| `--m3e-outlined-card-focus-text-color`          | Text color on focus.          |
+| `--m3e-outlined-card-focus-state-layer-color`   | State layer color on focus.   |
+| `--m3e-outlined-card-focus-state-layer-opacity` | State layer opacity on focus. |
+| `--m3e-outlined-card-focus-container-elevation` | Elevation level on focus.     |
+| `--m3e-outlined-card-focus-outline-color`       | Border color on focus.        |
+
+##### Pressed
+
+| Property                                          | Description                   |
+| ------------------------------------------------- | ----------------------------- |
+| `--m3e-outlined-card-pressed-text-color`          | Text color on press.          |
+| `--m3e-outlined-card-pressed-state-layer-color`   | State layer color on press.   |
+| `--m3e-outlined-card-pressed-state-layer-opacity` | State layer opacity on press. |
+| `--m3e-outlined-card-pressed-container-elevation` | Elevation level on press.     |
+| `--m3e-outlined-card-pressed-outline-color`       | Border color 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,126 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Card for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Card 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>
+      <m3e-card variant="filled"><div slot="content">Filled card</div></m3e-card>
+      <br />
+      <m3e-card variant="elevated"><div slot="content">Elevated card</div></m3e-card>
+      <br />
+      <m3e-card variant="outlined"><div slot="content">Outlined card</div></m3e-card>
+      <br />
+      <m3e-card style="width: 200px; height: 200px" inline>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Image card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 80px" inline orientation="horizontal">
+        <img
+          slot="header"
+          style="width: 80px"
+          src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480"
+        />
+        <div slot="content">Image card</div>
+      </m3e-card>
+      <br /><br />
+      <m3e-card style="width: 200px; height: 200px" actionable variant="filled" inline>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Filled actionable card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 200px" actionable variant="filled" inline disabled-interactive>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Filled disabled interactive actionable card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 200px" actionable variant="filled" inline disabled>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Filled disabled actionable card</div>
+      </m3e-card>
+      <br /><br />
+      <m3e-card style="width: 200px; height: 200px" actionable variant="elevated" inline>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Elevated actionable card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 200px" actionable variant="elevated" inline disabled-interactive>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Elevated disabled interactive actionable card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 200px" actionable variant="elevated" inline disabled>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Elevated disabled actionable card</div>
+      </m3e-card>
+      <br /><br />
+      <m3e-card style="width: 200px; height: 200px" actionable variant="outlined" inline>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Outlined actionable card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 200px" actionable variant="outlined" inline disabled-interactive>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Outlined disabled interactive actionable card</div>
+      </m3e-card>
+      <m3e-card style="width: 200px; height: 200px" actionable variant="outlined" inline disabled>
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Outlined disabled actionable card</div>
+      </m3e-card>
+      <br /><br />
+      <m3e-card style="width: 200px; height: 200px" actionable inline href="https://www.google.com" target="_blank">
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Actionable link card</div>
+      </m3e-card>
+      <m3e-card
+        style="width: 200px; height: 200px"
+        actionable
+        inline
+        disabled-interactive
+        href="https://www.google.com"
+        target="_blank"
+      >
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Disabled interactive actionable link card</div>
+      </m3e-card>
+      <m3e-card
+        style="width: 200px; height: 200px"
+        actionable
+        inline
+        disabled
+        href="https://www.google.com"
+        target="_blank"
+      >
+        <img slot="header" src="https://www.shutterstock.com/shutterstock/videos/1006393/thumb/1.jpg?ip=x480" />
+        <div slot="content">Disabled actionable link card</div>
+      </m3e-card>
+    </m3e-theme>
+  </body>
+</html>