@m3e/list 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,145 @@
+# @m3e/list
+
+The `@m3e/list` package provides expressive, accessible components for organizing and displaying lists of items. It includes both the `m3e-list` container and the `m3e-list-item` element, supporting rich content, flexible layout, and extensive theming via CSS custom properties.
+
+> **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/list
+```
+
+## 💻 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/list`, 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/list/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/list/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/list/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-list` — A list of items.
+- `m3e-list-item` — An item in a list.
+
+## 🧪 Examples
+
+The following example illustrates a list with a single item using all supported slots.
+
+> Note: This example uses the `@m3e/icon` package to present Material Design symbols, but any icon package can be substituted depending on your design system or preferences
+
+```html
+<m3e-list>
+  <m3e-list-item>
+    <m3e-icon slot="leading-icon" name="person"></m3e-icon>
+    <span slot="overline">Overline</span>
+    Headline
+    <span slot="supporting-text">Supporting text</span>
+    <span slot="trailing-supporting-text">100+</span>
+    <m3e-icon slot="trailing-icon" name="arrow_right"></m3e-icon>
+  </m3e-list-item>
+</m3e-list>
+```
+
+## 📖 API Reference
+
+### 🗂️ m3e-list
+
+This section details the slots and CSS custom properties available for the `m3e-list` component.
+
+#### 🧩 Slots
+
+| Slot        | Description                    |
+| ----------- | ------------------------------ |
+| _(default)_ | Renders the items of the list. |
+
+#### 🎛️ CSS Custom Properties
+
+| Property                              | Description                    |
+| ------------------------------------- | ------------------------------ |
+| `--m3e-list-block-padding`            | Vertical padding for the list. |
+| `--m3e-list-divider-inset-start-size` | Start inset for dividers.      |
+| `--m3e-list-divider-inset-end-size`   | End inset for dividers.        |
+
+### 🗂️ m3e-list-item
+
+This section details the slots and CSS custom properties available for the `m3e-list-item` component.
+
+#### 🧩 Slots
+
+| Slot                       | Description                           |
+| -------------------------- | ------------------------------------- |
+| _(default)_                | Renders the content of the list item. |
+| `leading-icon`             | Renders the leading icon.             |
+| `overline`                 | Renders the overline.                 |
+| `supporting-text`          | Renders the supporting text.          |
+| `trailing-supporting-text` | Renders the trailing supporting text. |
+| `trailing-icon`            | Renders the trailing icon.            |
+
+#### 🎛️ CSS Custom Properties
+
+| Property                                               | Description                                       |
+| ------------------------------------------------------ | ------------------------------------------------- |
+| `--m3e-list-item-spacing`                              | Horizontal gap between elements.                  |
+| `--m3e-list-item-padding-inline`                       | Horizontal padding for the list item.             |
+| `--m3e-list-item-padding-block`                        | Vertical padding for the list item.               |
+| `--m3e-list-item-height`                               | Minimum height of the list item.                  |
+| `--m3e-list-item-font-size`                            | Font size for main content.                       |
+| `--m3e-list-item-font-weight`                          | Font weight for main content.                     |
+| `--m3e-list-item-line-height`                          | Line height for main content.                     |
+| `--m3e-list-item-tracking`                             | Letter spacing for main content.                  |
+| `--m3e-list-item-overline-font-size`                   | Font size for overline slot.                      |
+| `--m3e-list-item-overline-font-weight`                 | Font weight for overline slot.                    |
+| `--m3e-list-item-overline-line-height`                 | Line height for overline slot.                    |
+| `--m3e-list-item-overline-tracking`                    | Letter spacing for overline slot.                 |
+| `--m3e-list-item-supporting-text-font-size`            | Font size for supporting text slot.               |
+| `--m3e-list-item-supporting-text-font-weight`          | Font weight for supporting text slot.             |
+| `--m3e-list-item-supporting-text-line-height`          | Line height for supporting text slot.             |
+| `--m3e-list-item-supporting-text-tracking`             | Letter spacing for supporting text slot.          |
+| `--m3e-list-item-trailing-supporting-text-font-size`   | Font size for trailing supporting text slot.      |
+| `--m3e-list-item-trailing-supporting-text-font-weight` | Font weight for trailing supporting text slot.    |
+| `--m3e-list-item-trailing-supporting-text-line-height` | Line height for trailing supporting text slot.    |
+| `--m3e-list-item-trailing-supporting-text-tracking`    | Letter spacing for trailing supporting text slot. |
+| `--m3e-list-item-icon-size`                            | Size for leading/trailing icons.                  |
+
+## 🤝 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,53 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>List for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="List 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-list>
+        <m3e-list-item>
+          <m3e-icon slot="leading-icon" name="person"></m3e-icon>
+          <span slot="overline">Overline</span>
+          Headline
+          <span slot="supporting-text">Supporting text</span>
+          <span slot="trailing-supporting-text">100+</span>
+          <m3e-icon slot="trailing-icon" name="arrow_right"></m3e-icon>
+        </m3e-list-item>
+      </m3e-list>
+    </m3e-theme>
+  </body>
+</html>

package/dist/css-custom-data.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-list-block-padding",
+      "description": "Vertical padding for the list container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-divider-inset-start-size",
+      "description": "Start inset for dividers within the list.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-divider-inset-end-size",
+      "description": "End inset for dividers within the list.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-spacing",
+      "description": "Horizontal gap between elements.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-padding-inline",
+      "description": "Horizontal padding for the list item.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-padding-block",
+      "description": "Vertical padding for the list item.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-height",
+      "description": "Minimum height of the list item.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-font-size",
+      "description": "Font size for main content.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-font-weight",
+      "description": "Font weight for main content.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-line-height",
+      "description": "Line height for main content.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-tracking",
+      "description": "Letter spacing for main content.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-overline-font-size",
+      "description": "Font size for overline slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-overline-font-weight",
+      "description": "Font weight for overline slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-overline-line-height",
+      "description": "Line height for overline slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-overline-tracking",
+      "description": "Letter spacing for overline slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-supporting-text-font-size",
+      "description": "Font size for supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-supporting-text-font-weight",
+      "description": "Font weight for supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-supporting-text-line-height",
+      "description": "Line height for supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-supporting-text-tracking",
+      "description": "Letter spacing for supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-trailing-supporting-text-font-size",
+      "description": "Font size for trailing supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-trailing-supporting-text-font-weight",
+      "description": "Font weight for trailing supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-trailing-supporting-text-line-height",
+      "description": "Line height for trailing supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-trailing-supporting-text-tracking",
+      "description": "Letter spacing for trailing supporting text slot.",
+      "values": []
+    },
+    {
+      "name": "--m3e-list-item-icon-size",
+      "description": "Size for leading/trailing icons.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}

package/dist/custom-elements.json

@@ -0,0 +1,247 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "\"./ListElement\""
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "\"./ListItemElement\""
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/ListElement.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "M3eListElement",
+          "cssProperties": [
+            {
+              "description": "Vertical padding for the list container.",
+              "name": "--m3e-list-block-padding"
+            },
+            {
+              "description": "Start inset for dividers within the list.",
+              "name": "--m3e-list-divider-inset-start-size"
+            },
+            {
+              "description": "End inset for dividers within the list.",
+              "name": "--m3e-list-divider-inset-end-size"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Renders the items of the list.",
+              "name": ""
+            }
+          ],
+          "members": [],
+          "mixins": [
+            {
+              "name": "Role",
+              "package": "@m3e/core"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "m3e-list",
+          "customElement": true,
+          "summary": "A list of items."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "M3eListElement",
+          "declaration": {
+            "name": "M3eListElement",
+            "module": "src/ListElement.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "m3e-list",
+          "declaration": {
+            "name": "M3eListElement",
+            "module": "src/ListElement.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/ListItemElement.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "M3eListItemElement",
+          "cssProperties": [
+            {
+              "description": "Horizontal gap between elements.",
+              "name": "--m3e-list-item-spacing"
+            },
+            {
+              "description": "Horizontal padding for the list item.",
+              "name": "--m3e-list-item-padding-inline"
+            },
+            {
+              "description": "Vertical padding for the list item.",
+              "name": "--m3e-list-item-padding-block"
+            },
+            {
+              "description": "Minimum height of the list item.",
+              "name": "--m3e-list-item-height"
+            },
+            {
+              "description": "Font size for main content.",
+              "name": "--m3e-list-item-font-size"
+            },
+            {
+              "description": "Font weight for main content.",
+              "name": "--m3e-list-item-font-weight"
+            },
+            {
+              "description": "Line height for main content.",
+              "name": "--m3e-list-item-line-height"
+            },
+            {
+              "description": "Letter spacing for main content.",
+              "name": "--m3e-list-item-tracking"
+            },
+            {
+              "description": "Font size for overline slot.",
+              "name": "--m3e-list-item-overline-font-size"
+            },
+            {
+              "description": "Font weight for overline slot.",
+              "name": "--m3e-list-item-overline-font-weight"
+            },
+            {
+              "description": "Line height for overline slot.",
+              "name": "--m3e-list-item-overline-line-height"
+            },
+            {
+              "description": "Letter spacing for overline slot.",
+              "name": "--m3e-list-item-overline-tracking"
+            },
+            {
+              "description": "Font size for supporting text slot.",
+              "name": "--m3e-list-item-supporting-text-font-size"
+            },
+            {
+              "description": "Font weight for supporting text slot.",
+              "name": "--m3e-list-item-supporting-text-font-weight"
+            },
+            {
+              "description": "Line height for supporting text slot.",
+              "name": "--m3e-list-item-supporting-text-line-height"
+            },
+            {
+              "description": "Letter spacing for supporting text slot.",
+              "name": "--m3e-list-item-supporting-text-tracking"
+            },
+            {
+              "description": "Font size for trailing supporting text slot.",
+              "name": "--m3e-list-item-trailing-supporting-text-font-size"
+            },
+            {
+              "description": "Font weight for trailing supporting text slot.",
+              "name": "--m3e-list-item-trailing-supporting-text-font-weight"
+            },
+            {
+              "description": "Line height for trailing supporting text slot.",
+              "name": "--m3e-list-item-trailing-supporting-text-line-height"
+            },
+            {
+              "description": "Letter spacing for trailing supporting text slot.",
+              "name": "--m3e-list-item-trailing-supporting-text-tracking"
+            },
+            {
+              "description": "Size for leading/trailing icons.",
+              "name": "--m3e-list-item-icon-size"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Renders the content of the list item.",
+              "name": ""
+            },
+            {
+              "description": "Renders the leading icon of the list item.",
+              "name": "leading-icon"
+            },
+            {
+              "description": "Renders the overline of the list item.",
+              "name": "overline"
+            },
+            {
+              "description": "Renders the supporting text of the list item.",
+              "name": "supporting-text"
+            },
+            {
+              "description": "Renders the trailing supporting text of the list item.",
+              "name": "trailing-supporting-text"
+            },
+            {
+              "description": "Renders the trailing icon of the list item.",
+              "name": "trailing-icon"
+            }
+          ],
+          "members": [],
+          "mixins": [
+            {
+              "name": "Role",
+              "package": "@m3e/core"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "m3e-list-item",
+          "customElement": true,
+          "summary": "An item in a list."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "M3eListItemElement",
+          "declaration": {
+            "name": "M3eListItemElement",
+            "module": "src/ListItemElement.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "m3e-list-item",
+          "declaration": {
+            "name": "M3eListItemElement",
+            "module": "src/ListItemElement.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/html-custom-data.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-html-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "tags": [
+    {
+      "name": "m3e-list",
+      "description": "A list of items.\n---\n\n\n### **Slots:**\n - _default_ - Renders the items of the list.\n\n### **CSS Properties:**\n - **--m3e-list-block-padding** - Vertical padding for the list container. _(default: undefined)_\n- **--m3e-list-divider-inset-start-size** - Start inset for dividers within the list. _(default: undefined)_\n- **--m3e-list-divider-inset-end-size** - End inset for dividers within the list. _(default: undefined)_",
+      "attributes": [],
+      "references": []
+    },
+    {
+      "name": "m3e-list-item",
+      "description": "An item in a list.\n---\n\n\n### **Slots:**\n - _default_ - Renders the content of the list item.\n- **leading-icon** - Renders the leading icon of the list item.\n- **overline** - Renders the overline of the list item.\n- **supporting-text** - Renders the supporting text of the list item.\n- **trailing-supporting-text** - Renders the trailing supporting text of the list item.\n- **trailing-icon** - Renders the trailing icon of the list item.\n\n### **CSS Properties:**\n - **--m3e-list-item-spacing** - Horizontal gap between elements. _(default: undefined)_\n- **--m3e-list-item-padding-inline** - Horizontal padding for the list item. _(default: undefined)_\n- **--m3e-list-item-padding-block** - Vertical padding for the list item. _(default: undefined)_\n- **--m3e-list-item-height** - Minimum height of the list item. _(default: undefined)_\n- **--m3e-list-item-font-size** - Font size for main content. _(default: undefined)_\n- **--m3e-list-item-font-weight** - Font weight for main content. _(default: undefined)_\n- **--m3e-list-item-line-height** - Line height for main content. _(default: undefined)_\n- **--m3e-list-item-tracking** - Letter spacing for main content. _(default: undefined)_\n- **--m3e-list-item-overline-font-size** - Font size for overline slot. _(default: undefined)_\n- **--m3e-list-item-overline-font-weight** - Font weight for overline slot. _(default: undefined)_\n- **--m3e-list-item-overline-line-height** - Line height for overline slot. _(default: undefined)_\n- **--m3e-list-item-overline-tracking** - Letter spacing for overline slot. _(default: undefined)_\n- **--m3e-list-item-supporting-text-font-size** - Font size for supporting text slot. _(default: undefined)_\n- **--m3e-list-item-supporting-text-font-weight** - Font weight for supporting text slot. _(default: undefined)_\n- **--m3e-list-item-supporting-text-line-height** - Line height for supporting text slot. _(default: undefined)_\n- **--m3e-list-item-supporting-text-tracking** - Letter spacing for supporting text slot. _(default: undefined)_\n- **--m3e-list-item-trailing-supporting-text-font-size** - Font size for trailing supporting text slot. _(default: undefined)_\n- **--m3e-list-item-trailing-supporting-text-font-weight** - Font weight for trailing supporting text slot. _(default: undefined)_\n- **--m3e-list-item-trailing-supporting-text-line-height** - Line height for trailing supporting text slot. _(default: undefined)_\n- **--m3e-list-item-trailing-supporting-text-tracking** - Letter spacing for trailing supporting text slot. _(default: undefined)_\n- **--m3e-list-item-icon-size** - Size for leading/trailing icons. _(default: undefined)_",
+      "attributes": [],
+      "references": []
+    }
+  ]
+}