@m3e/nav-bar 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,175 @@
+# @m3e/nav-bar
+
+The `m3e-nav-bar` and `m3e-nav-item` components provide a navigation bar and interactive items for switching between primary destinations in your application. Designed for smaller devices, they support 3-5 interactive items, 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-bar
+```
+
+## 💻 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-bar`, 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-bar/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/nav-bar/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-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"
+    }
+  }
+</script>
+```
+
+> For production, use index.min.js, a11y.min.js, and layout.min.js for faster load times.
+
+## 🗂️ Elements
+
+- `m3e-nav-bar` — A horizontal bar, typically used on smaller devices, that allows a user to switch between 3-5 views.
+- `m3e-nav-item` — An item, placed in a navigation bar or rail, used to navigate to destinations in an application.
+
+## 🧪 Example
+
+```html
+<m3e-nav-bar>
+  <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-bar>
+```
+
+## 📖 API Reference
+
+### 🗂️ m3e-nav-bar
+
+This section details the attributes, slots, events and CSS custom properties available for the `m3e-nav-bar` component.
+
+#### ⚙️ Attributes
+
+| Attribute | Type                                    | Default     | Description                                       |
+| --------- | --------------------------------------- | ----------- | ------------------------------------------------- |
+| `mode`    | `"compact"` \| `"expanded"` \| `"auto"` | `"compact"` | The mode in which items in the bar are presented. |
+
+#### 🔔 Events
+
+| Event    | Description                                        |
+| -------- | -------------------------------------------------- |
+| `change` | Emitted when the selected state of an item changes |
+
+#### 🧩 Slots
+
+| Slot        | Description                   |
+| ----------- | ----------------------------- |
+| _(default)_ | Renders the items of the bar. |
+
+#### 🎛️ CSS Custom Properties
+
+| Property                            | Description                             |
+| ----------------------------------- | --------------------------------------- |
+| `--m3e-nav-bar-height`              | Height of the navigation bar.           |
+| `--m3e-nav-bar-container-color`     | Background color of the navigation bar. |
+| `--m3e-nav-bar-vertical-item-width` | Minimum width of vertical nav items.    |
+
+### 🗂️ m3e-nav-item
+
+This section details the attributes, slots, events and CSS custom properties available for the `m3e-nav-item` component.
+
+#### ⚙️ Attributes
+
+| Attribute              | Type                           | Default      | Description                                  |
+| ---------------------- | ------------------------------ | ------------ | -------------------------------------------- |
+| `disabled`             | `boolean`                      | `false`      | Whether the item is disabled.                |
+| `disabled-interactive` | `boolean`                      | `false`      | Whether the item is disabled and interactive |
+| `download`             | `string`                       |              | Download target for link button.             |
+| `href`                 | `string`                       |              | URL for the link button.                     |
+| `orientation`          | `"vertical"` \| `"horizontal"` | `"vertical"` | The layout orientation of the item.          |
+| `rel`                  | `string`                       |              | Relationship for the link button.            |
+| `selected`             | `boolean`                      | `false`      | Whether the item is selected.                |
+| `target`               | `string`                       |              | Target for the link button.                  |
+
+#### 🔔 Events
+
+| Event    | Description                              |
+| -------- | ---------------------------------------- |
+| `input`  | Emitted when the selected state changes. |
+| `change` | Emitted when the selected state changes. |
+
+#### 🧩 Slots
+
+| Slot            | Description                                 |
+| --------------- | ------------------------------------------- |
+| _(default)_     | Renders the label of the item.              |
+| `icon`          | Renders the icon of the item.               |
+| `selected-icon` | Renders the icon when the item is selected. |
+
+#### 🎛️ CSS Custom Properties
+
+| Property                                            | Description                                  |
+| --------------------------------------------------- | -------------------------------------------- |
+| `--m3e-nav-item-label-text-font-size`               | Font size for the label text.                |
+| `--m3e-nav-item-label-text-font-weight`             | Font weight for the label text.              |
+| `--m3e-nav-item-label-text-line-height`             | Line height for the label text.              |
+| `--m3e-nav-item-label-text-tracking`                | Letter spacing for the label text.           |
+| `--m3e-nav-item-shape`                              | Border radius of the nav item.               |
+| `--m3e-nav-item-icon-size`                          | Size of the icon.                            |
+| `--m3e-nav-item-spacing`                            | Spacing between icon and label.              |
+| `--m3e-nav-item-inactive-label-text-color`          | Color of the label text when inactive.       |
+| `--m3e-nav-item-inactive-icon-color`                | Color of the icon when inactive.             |
+| `--m3e-nav-item-inactive-hover-state-layer-color`   | State layer color on hover when inactive.    |
+| `--m3e-nav-item-inactive-focus-state-layer-color`   | State layer color on focus when inactive.    |
+| `--m3e-nav-item-inactive-pressed-state-layer-color` | State layer color on press when inactive.    |
+| `--m3e-nav-item-active-label-text-color`            | Color of the label text when active.         |
+| `--m3e-nav-item-active-icon-color`                  | Color of the icon when active.               |
+| `--m3e-nav-item-active-container-color`             | Container color when active.                 |
+| `--m3e-nav-item-active-hover-state-layer-color`     | State layer color on hover when active.      |
+| `--m3e-nav-item-active-focus-state-layer-color`     | State layer color on focus when active.      |
+| `--m3e-nav-item-active-pressed-state-layer-color`   | State layer color on press when active.      |
+| `--m3e-nav-item-focus-ring-shape`                   | Border radius for the focus ring.            |
+| `--m3e-nav-item-disabled-label-text-color`          | Color of the label text when disabled.       |
+| `--m3e-nav-item-disabled-label-text-opacity`        | Opacity of the label text when disabled.     |
+| `--m3e-nav-item-disabled-icon-color`                | Color of the icon when disabled.             |
+| `--m3e-nav-item-disabled-icon-opacity`              | Opacity of the icon when disabled.           |
+| `--m3e-horizontal-nav-item-padding`                 | Padding for horizontal orientation.          |
+| `--m3e-horizontal-nav-item-active-indicator-height` | Height of the active indicator (horizontal). |
+| `--m3e-vertical-nav-item-active-indicator-width`    | Width of the active indicator (vertical).    |
+| `--m3e-vertical-nav-item-active-indicator-height`   | Height of the active indicator (vertical).   |
+| `--m3e-vertical-nav-item-active-indicator-margin`   | Margin for the active indicator (vertical).  |
+
+## 🤝 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,65 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Navigation Bar for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Navigation Bar 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"
+        }
+      }
+    </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-nav-bar onchange="console.log(this.selected)">
+        <m3e-nav-item><m3e-icon slot="icon" filled name="news"></m3e-icon>News</m3e-nav-item>
+        <m3e-nav-item disabled><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-bar>
+      <br /><br />
+      <m3e-nav-bar mode="expanded" onchange="console.log(this.selected)">
+        <m3e-nav-item><m3e-icon slot="icon" filled name="news"></m3e-icon>News</m3e-nav-item>
+        <m3e-nav-item disabled><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-bar>
+      <br /><br />
+      <m3e-nav-bar mode="auto" onchange="console.log(this.selected)">
+        <m3e-nav-item><m3e-icon slot="icon" filled 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-bar>
+    </m3e-theme>
+  </body>
+</html>

package/dist/css-custom-data.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-nav-bar-height",
+      "description": "Height of the navigation bar.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-bar-container-color",
+      "description": "Background color of the navigation bar container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-bar-vertical-item-width",
+      "description": "Minimum width of vertical nav items.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-label-text-font-size",
+      "description": "Font size for the label text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-label-text-font-weight",
+      "description": "Font weight for the label text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-label-text-line-height",
+      "description": "Line height for the label text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-label-text-tracking",
+      "description": "Letter spacing for the label text.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-shape",
+      "description": "Border radius of the nav item.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-icon-size",
+      "description": "Size of the icon.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-spacing",
+      "description": "Spacing between icon and label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-inactive-label-text-color",
+      "description": "Color of the label text when inactive.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-inactive-icon-color",
+      "description": "Color of the icon when inactive.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-inactive-hover-state-layer-color",
+      "description": "State layer color on hover when inactive.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-inactive-focus-state-layer-color",
+      "description": "State layer color on focus when inactive.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-inactive-pressed-state-layer-color",
+      "description": "State layer color on press when inactive.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-active-label-text-color",
+      "description": "Color of the label text when active/selected.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-active-icon-color",
+      "description": "Color of the icon when active/selected.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-active-container-color",
+      "description": "Container color when active/selected.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-active-hover-state-layer-color",
+      "description": "State layer color on hover when active.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-active-focus-state-layer-color",
+      "description": "State layer color on focus when active.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-active-pressed-state-layer-color",
+      "description": "State layer color on press when active.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-focus-ring-shape",
+      "description": "Border radius for the focus ring.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-disabled-label-text-color",
+      "description": "Color of the label text when disabled.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-disabled-label-text-opacity",
+      "description": "Opacity of the label text when disabled.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-disabled-icon-color",
+      "description": "Color of the icon when disabled.",
+      "values": []
+    },
+    {
+      "name": "--m3e-nav-item-disabled-icon-opacity",
+      "description": "Opacity of the icon when disabled.",
+      "values": []
+    },
+    {
+      "name": "--m3e-horizontal-nav-item-padding",
+      "description": "Padding for horizontal orientation.",
+      "values": []
+    },
+    {
+      "name": "--m3e-horizontal-nav-item-active-indicator-height",
+      "description": "Height of the active indicator in horizontal orientation.",
+      "values": []
+    },
+    {
+      "name": "--m3e-vertical-nav-item-active-indicator-width",
+      "description": "Width of the active indicator in vertical orientation.",
+      "values": []
+    },
+    {
+      "name": "--m3e-vertical-nav-item-active-indicator-height",
+      "description": "Height of the active indicator in vertical orientation.",
+      "values": []
+    },
+    {
+      "name": "--m3e-vertical-nav-item-active-indicator-margin",
+      "description": "Margin for the active indicator in vertical orientation.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}