@m3e/nav-rail 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,131 @@
+# @m3e/nav-rail
+
+The `m3e-nav-rail` component extends `@m3e/nav-bar` to provide a vertical navigation rail and interactive items for switching between primary destinations in your application. Designed for larger devices, the nav rail supports compact and expanded modes, orientation, selection, 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/nav-rail
+```
+
+## 💻 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/nav-rail`, 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/nav-rail/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/nav-rail/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/nav-rail/dist/index.js"></script>
+```
+
+You also need a module script for `@m3e/nav-bar` due to it being a dependency.
+
+```html
+<script type="module" src="/node_modules/@m3e/nav-bar/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",
+      "@m3e/core/layout": "/node_modules/@m3e/core/dist/layout.js",
+      "@m3e/nav-bar": "/node_modules/@m3e/nav-bar/dist/index.js"
+    }
+  }
+</script>
+```
+
+> For production, use index.min.js, a11y.min.js, and layout.min.js for faster load times.
+
+## 🗂️ Elements
+
+- `m3e-nav-rail` — A vertical bar, typically used on larger devices, that allows a user to switch between views.
+
+## 🧪 Example
+
+The following example illustrates a nav rail whose expanded state is automatically determined by the current screen size. In addition, a toggle button is used to allow the user to manually toggle the expanded state.
+
+```html
+<m3e-nav-rail id="nav-rail" mode="auto">
+  <m3e-icon-button toggle>
+    <m3e-icon name="menu"></m3e-icon>
+    <m3e-icon slot="selected" name="menu_open"></m3e-icon>
+    <m3e-nav-rail-toggle for="nav-rail"></m3e-nav-rail-toggle>
+  </m3e-icon-button>
+  <m3e-fab size="small">
+    <m3e-icon name="edit"></m3e-icon>
+    <span slot="label">Extended</span>
+  </m3e-fab>
+  <m3e-nav-item><m3e-icon slot="icon" name="news"></m3e-icon>News</m3e-nav-item>
+  <m3e-nav-item><m3e-icon slot="icon" name="globe"></m3e-icon>Global</m3e-nav-item>
+  <m3e-nav-item><m3e-icon slot="icon" name="star"></m3e-icon>For you</m3e-nav-item>
+  <m3e-nav-item><m3e-icon slot="icon" name="newsstand"></m3e-icon>Trending</m3e-nav-item>
+</m3e-nav-rail>
+```
+
+## 📖 API Reference
+
+This section details the attributes, slots, events and CSS custom properties available for the `m3e-nav-rail` component.
+
+### ⚙️ Attributes
+
+| Attribute | Type                              | Default | Description                                        |
+| --------- | --------------------------------- | ------- | -------------------------------------------------- |
+| mode      | "compact" \| "expanded" \| "auto" | auto    | The mode in which items in the rail are presented. |
+
+### 🔔 Events
+
+| Event  | Description                                         |
+| ------ | --------------------------------------------------- |
+| change | Emitted when the selected state of an item changes. |
+
+### 🧩 Slots
+
+| Slot        | Description                    |
+| ----------- | ------------------------------ |
+| _(default)_ | Renders the items of the rail. |
+
+### 🎛️ CSS Custom Properties
+
+| Property                                    | Description                                     |
+| ------------------------------------------- | ----------------------------------------------- |
+| `--m3e-nav-rail-top-space`                  | Top block padding for the nav rail.             |
+| `--m3e-nav-rail-bottom-space`               | Bottom block padding for the nav rail.          |
+| `--m3e-nav-rail-compact-width`              | Width of the nav rail in compact mode.          |
+| `--m3e-nav-rail-expanded-inline-padding`    | Inline padding for expanded nav rail.           |
+| `--m3e-nav-rail-expanded-min-width`         | Minimum width of the nav rail in expanded mode. |
+| `--m3e-nav-rail-expanded-max-width`         | Maximum width of the nav rail in expanded mode. |
+| `--m3e-nav-rail-expanded-item-height`       | Height of nav items in expanded mode.           |
+| `--m3e-nav-rail-button-item-space`          | Space below icon buttons and FABs.              |
+| `--m3e-nav-rail-expanded-icon-button-inset` | Inset for icon buttons in expanded mode.        |
+
+## 🤝 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,63 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Navigation Rail for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Navigation Rail 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",
+          "@m3e/core/layout": "../../core/dist/layout.min.js",
+          "@m3e/nav-bar": "../../nav-bar/dist/index.min.js"
+        }
+      }
+    </script>
+    <script type="module" src="../../icon/dist/index.min.js"></script>
+    <script type="module" src="../../icon-button/dist/index.min.js"></script>
+    <script type="module" src="../../theme/dist/index.min.js"></script>
+    <script type="module" src="../../fab/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-nav-rail mode="auto" onchange="console.log(this.selected)" id="nav-rail">
+        <m3e-icon-button toggle>
+          <m3e-icon name="menu"></m3e-icon>
+          <m3e-icon slot="selected" name="menu_open"></m3e-icon>
+          <m3e-nav-rail-toggle for="nav-rail"></m3e-nav-rail-toggle>
+        </m3e-icon-button>
+        <m3e-fab size="small">
+          <m3e-icon name="edit"></m3e-icon>
+          <span slot="label">Extended</span>
+        </m3e-fab>
+        <m3e-nav-item><m3e-icon slot="icon" name="news"></m3e-icon>News</m3e-nav-item>
+        <m3e-nav-item><m3e-icon slot="icon" name="globe"></m3e-icon>Global</m3e-nav-item>
+        <m3e-nav-item><m3e-icon slot="icon" name="star"></m3e-icon>For you</m3e-nav-item>
+        <m3e-nav-item><m3e-icon slot="icon" name="newsstand"></m3e-icon>Trending</m3e-nav-item>
+      </m3e-nav-rail>
+    </m3e-theme>
+  </body>
+</html>

package/dist/css-custom-data.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-nav-rail-top-space",
+      "description": "Top block padding for the nav rail.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-bottom-space",
+      "description": "Bottom block padding for the nav rail.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-compact-width",
+      "description": "Width of the nav rail in compact mode.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-expanded-inline-padding",
+      "description": "Inline padding for expanded nav rail.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-expanded-min-width",
+      "description": "Minimum width of the nav rail in expanded mode.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-expanded-max-width",
+      "description": "Maximum width of the nav rail in expanded mode.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-expanded-item-height",
+      "description": "Height of nav items in expanded mode.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-button-item-space",
+      "description": "Space below icon buttons and FABs.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-rail-expanded-icon-button-inset",
+      "description": "Inset for icon buttons in expanded mode.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}

package/dist/custom-elements.json

@@ -0,0 +1,260 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "\"./NavRailElement\""
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "\"./NavRailToggleElement\""
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/NavRailElement.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "M3eNavRailElement",
+          "cssProperties": [
+            {
+              "description": "Top block padding for the nav rail.",
+              "name": "--m3e-nav-rail-top-space"
+            },
+            {
+              "description": "Bottom block padding for the nav rail.",
+              "name": "--m3e-nav-rail-bottom-space"
+            },
+            {
+              "description": "Width of the nav rail in compact mode.",
+              "name": "--m3e-nav-rail-compact-width"
+            },
+            {
+              "description": "Inline padding for expanded nav rail.",
+              "name": "--m3e-nav-rail-expanded-inline-padding"
+            },
+            {
+              "description": "Minimum width of the nav rail in expanded mode.",
+              "name": "--m3e-nav-rail-expanded-min-width"
+            },
+            {
+              "description": "Maximum width of the nav rail in expanded mode.",
+              "name": "--m3e-nav-rail-expanded-max-width"
+            },
+            {
+              "description": "Height of nav items in expanded mode.",
+              "name": "--m3e-nav-rail-expanded-item-height"
+            },
+            {
+              "description": "Space below icon buttons and FABs.",
+              "name": "--m3e-nav-rail-button-item-space"
+            },
+            {
+              "description": "Inset for icon buttons in expanded mode.",
+              "name": "--m3e-nav-rail-expanded-icon-button-inset"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "#focusKeyManager",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "#keyDownHandler",
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "#handleKeyDown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ]
+            }
+          ],
+          "events": [
+            {
+              "description": "Emitted when the selected state of an item changes.",
+              "name": "change"
+            }
+          ],
+          "attributes": [
+            {
+              "description": "The mode in which items in the rail are presented.",
+              "name": "mode"
+            }
+          ],
+          "superclass": {
+            "name": "M3eNavBarElement",
+            "package": "@m3e/nav-bar"
+          },
+          "tagName": "m3e-nav-rail",
+          "customElement": true,
+          "summary": "A vertical bar, typically used on larger devices, that allows a user to switch between views."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "M3eNavRailElement",
+          "declaration": {
+            "name": "M3eNavRailElement",
+            "module": "src/NavRailElement.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "m3e-nav-rail",
+          "declaration": {
+            "name": "M3eNavRailElement",
+            "module": "src/NavRailElement.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/NavRailToggleElement.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "An element, nested within a clickable element, used to toggle the expanded state of a navigation rail.",
+          "name": "M3eNavRailToggleElement",
+          "members": [
+            {
+              "kind": "field",
+              "name": "#clickHandler",
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "#mutationController",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new MutationController(this, { target: null, config: { attributeFilter: [\"class\"] }, callback: () => this.#updateToggle(), })"
+            },
+            {
+              "kind": "method",
+              "name": "attach",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "control",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "detach",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "#handleClick",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "#updateToggle",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            }
+          ],
+          "mixins": [
+            {
+              "name": "HtmlFor",
+              "package": "@m3e/core"
+            },
+            {
+              "name": "Role",
+              "package": "@m3e/core"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "m3e-nav-rail-toggle",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "M3eNavRailToggleElement",
+          "declaration": {
+            "name": "M3eNavRailToggleElement",
+            "module": "src/NavRailToggleElement.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "m3e-nav-rail-toggle",
+          "declaration": {
+            "name": "M3eNavRailToggleElement",
+            "module": "src/NavRailToggleElement.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/html-custom-data.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-html-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "tags": [
+    {
+      "name": "m3e-nav-rail",
+      "description": "A vertical bar, typically used on larger devices, that allows a user to switch between views.\n---\n\n\n### **Events:**\n - **change** - Emitted when the selected state of an item changes.\n\n### **CSS Properties:**\n - **--m3e-nav-rail-top-space** - Top block padding for the nav rail. _(default: undefined)_\n- **--m3e-nav-rail-bottom-space** - Bottom block padding for the nav rail. _(default: undefined)_\n- **--m3e-nav-rail-compact-width** - Width of the nav rail in compact mode. _(default: undefined)_\n- **--m3e-nav-rail-expanded-inline-padding** - Inline padding for expanded nav rail. _(default: undefined)_\n- **--m3e-nav-rail-expanded-min-width** - Minimum width of the nav rail in expanded mode. _(default: undefined)_\n- **--m3e-nav-rail-expanded-max-width** - Maximum width of the nav rail in expanded mode. _(default: undefined)_\n- **--m3e-nav-rail-expanded-item-height** - Height of nav items in expanded mode. _(default: undefined)_\n- **--m3e-nav-rail-button-item-space** - Space below icon buttons and FABs. _(default: undefined)_\n- **--m3e-nav-rail-expanded-icon-button-inset** - Inset for icon buttons in expanded mode. _(default: undefined)_",
+      "attributes": [
+        {
+          "name": "mode",
+          "description": "The mode in which items in the rail are presented.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
+    {
+      "name": "m3e-nav-rail-toggle",
+      "description": "An element, nested within a clickable element, used to toggle the expanded state of a navigation rail.\n---\n",
+      "attributes": [],
+      "references": []
+    }
+  ]
+}