@m3e/tabs 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,186 @@
+# @m3e/tabs
+
+The `m3e-tabs` component provides a structured navigation surface for organizing content into distinct views, where only one view is visible at a time. It supports scrollable tab headers with optional pagination, accessible labeling for navigation controls, and configurable header positioning to suit various layout contexts. Two visual variants are available: `primary`, which emphasizes active indicators and shape styling for prominent navigation, and `secondary`, which offers a more subtle presentation with reduced indicator thickness. Stretch behavior allows tabs to expand and align rhythmically within their container, consistent with Material 3 guidance.
+
+> **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/tabs
+```
+
+## 💻 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/tabs`, 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/tabs/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/tabs/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/tabs/dist/index.js"></script>
+```
+
+You also need a module script for `@m3e/icon-button` and `m3e/slide-group` due to these being a dependency.
+
+```html
+<script type="module" src="/node_modules/@m3e/icon-button/dist/index.js"></script>
+<script type="module" src="/node_modules/@m3e/slide-group/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"
+    }
+  }
+</script>
+```
+
+> For production, use index.min.js and a11y.min.js for faster load times.
+
+## 🗂️ Elements
+
+- `m3e-tabs` — Organizes content into separate views where only one view can be visible at a time.
+- `m3e-tab` — An interactive element that, when activated, presents an associated tab panel.
+- `m3e-tab-panel` — A panel presented for a tab.
+
+## 🧪 Examples
+
+The following example illustrates using the `m3e-tabs`, `m3e-tab`, and `m3e-tab-panel` components to present secondary tabs.
+
+```html
+<m3e-tabs>
+  <m3e-tab selected for="videos"><m3e-icon slot="icon" name="videocam"></m3e-icon>Video</m3e-tab>
+  <m3e-tab for="photos"><m3e-icon slot="icon" name="photo"></m3e-icon>Photos</m3e-tab>
+  <m3e-tab for="audio"><m3e-icon slot="icon" name="music_note"></m3e-icon>Audio</m3e-tab>
+  <m3e-tab-panel id="videos">Videos</m3e-tab-panel>
+  <m3e-tab-panel id="photos">Photos</m3e-tab-panel>
+  <m3e-tab-panel id="audio">Audio</m3e-tab-panel>
+</m3e-tabs>
+```
+
+## 📖 API Reference
+
+### 🗂️ m3e-tabs
+
+This section details the attributes, events, slots and CSS custom properties available for the `m3e-tabs` component.
+
+#### ⚙️ Attributes
+
+| Attribute             | Type                         | Default           | Description                                                                 |
+| --------------------- | ---------------------------- | ----------------- | --------------------------------------------------------------------------- |
+| `disable-pagination`  | `boolean`                    | `false`           | Whether scroll buttons are disabled.                                        |
+| `header-position`     | `"before"` \| `"after"`      | `"before"`        | The position of the tab headers.                                            |
+| `next-page-label`     | `string`                     | `"Next page"`     | The accessible label given to the button used to move to the previous page. |
+| `previous-page-label` | `string`                     | `"Previous page"` | The accessible label given to the button used to move to the next page.     |
+| `stretch`             | `boolean`                    | `false`           | Whether tabs are stretched to fill the header.                              |
+| `variant`             | `"primary"` \| `"secondary"` | `"secondary"`     | The appearance variant of the tabs.                                         |
+
+#### 🔔 Events
+
+| Event    | Description                            |
+| -------- | -------------------------------------- |
+| `change` | Emitted when the selected tab changes. |
+
+#### 🧩 Slots
+
+| Slot        | Description                                                           |
+| ----------- | --------------------------------------------------------------------- |
+| _(default)_ | Renders the tabs.                                                     |
+| `panel`     | Renders the panels of the tabs.                                       |
+| `next-icon` | Renders the icon to present for the next button used to paginate.     |
+| `prev-icon` | Renders the icon to present for the previous button used to paginate. |
+
+#### 🎛️ CSS Custom Properties
+
+| Property                                           | Description                                                                      |
+| -------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `--m3e-tabs-paginator-button-icon-size`            | Overrides the icon size for paginator buttons.                                   |
+| `--m3e-tabs-active-indicator-color`                | Color of the active tab indicator.                                               |
+| `--m3e-tabs-primary-before-active-indicator-shape` | Border radius for active indicator when header is before and variant is primary. |
+| `--m3e-tabs-primary-after-active-indicator-shape`  | Border radius for active indicator when header is after and variant is primary.  |
+| `--m3e-tabs-primary-active-indicator-inset`        | Inset for primary variant's active indicator.                                    |
+| `--m3e-tabs-primary-active-indicator-thickness`    | Thickness for primary variant's active indicator.                                |
+| `--m3e-tabs-secondary-active-indicator-thickness`  | Thickness for secondary variant's active indicator.                              |
+
+### 🗂️ m3e-tab
+
+This section details the attributes, slots and CSS custom properties available for the `m3e-tab` component.
+
+#### ⚙️ Attributes
+
+| Attribute  | Type      | Default | Description                                                             |
+| ---------- | --------- | ------- | ----------------------------------------------------------------------- |
+| `disabled` | `boolean` | `false` | Whether the element is disabled.                                        |
+| `for`      | `string`  |         | The query selector used to specify the element related to this element. |
+| `selected` | `boolean` | `false` | Whether the element is selected.                                        |
+
+#### 🧩 Slots
+
+| Slot        | Description                             |
+| ----------- | --------------------------------------- |
+| _(default)_ | Renders the label of the tab.           |
+| `icon`      | Renders an icon before the tab's label. |
+
+#### 🎛️ CSS Custom Properties
+
+| Property                                     | Description                                 |
+| -------------------------------------------- | ------------------------------------------- |
+| `--m3e-tab-font-size`                        | Font size for tab label.                    |
+| `--m3e-tab-font-weight`                      | Font weight for tab label.                  |
+| `--m3e-tab-line-height`                      | Line height for tab label.                  |
+| `--m3e-tab-tracking`                         | Letter spacing for tab label.               |
+| `--m3e-tab-padding-start`                    | Padding on the inline start of the tab.     |
+| `--m3e-tab-padding-end`                      | Padding on the inline end of the tab.       |
+| `--m3e-tab-focus-ring-shape`                 | Border radius for the focus ring.           |
+| `--m3e-tab-selected-color`                   | Text color for selected tab.                |
+| `--m3e-tab-selected-container-hover-color`   | Hover state-layer color for selected tab.   |
+| `--m3e-tab-selected-container-focus-color`   | Focus state-layer color for selected tab.   |
+| `--m3e-tab-selected-ripple-color`            | Ripple color for selected tab.              |
+| `--m3e-tab-unselected-color`                 | Text color for unselected tab.              |
+| `--m3e-tab-unselected-container-hover-color` | Hover state-layer color for unselected tab. |
+| `--m3e-tab-unselected-container-focus-color` | Focus state-layer color for unselected tab. |
+| `--m3e-tab-unselected-ripple-color`          | Ripple color for unselected tab.            |
+| `--m3e-tab-disabled-color`                   | Text color for disabled tab.                |
+| `--m3e-tab-disabled-opacity`                 | Text opacity for disabled tab.              |
+| `--m3e-tab-spacing`                          | Column gap between icon and label.          |
+| `--m3e-tab-icon-size`                        | Font size for slotted icon.                 |
+
+### 🗂️ m3e-tab-panel
+
+This section details the slots available for the `m3e-tab-panel` component.
+
+#### 🧩 Slots
+
+| Slot        | Description                       |
+| ----------- | --------------------------------- |
+| _(default)_ | Renders the content of the panel. |
+
+## 🤝 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,103 @@
+<!doctype html>
+<html lang="en" style="overflow-y: auto">
+  <head>
+    <title>Tabs for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Tabs 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"
+        }
+      }
+    </script>
+    <script type="module" src="../../theme/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="../../slide-group/dist/index.min.js"></script>
+    <script type="module" src="../dist/index.min.js"></script>
+    <style>
+      body {
+        font-family: "Roboto";
+      }
+      *:not(:defined) {
+        display: none;
+      }
+      label {
+        display: inline-flex;
+        align-items: center;
+        justify-content: space-between;
+        width: 400px;
+        margin-bottom: 1rem;
+      }
+    </style>
+  </head>
+  <body>
+    <m3e-theme strong-focus motion="expressive">
+      <m3e-tabs>
+        <m3e-tab selected for="videos"><m3e-icon slot="icon" name="videocam"></m3e-icon>Video</m3e-tab>
+        <m3e-tab for="photos"><m3e-icon slot="icon" name="photo"></m3e-icon>Photos</m3e-tab>
+        <m3e-tab for="audio"><m3e-icon slot="icon" name="music_note"></m3e-icon>Audio</m3e-tab>
+        <m3e-tab-panel id="videos">Videos</m3e-tab-panel>
+        <m3e-tab-panel id="photos">Photos</m3e-tab-panel>
+        <m3e-tab-panel id="audio">Audio</m3e-tab-panel>
+      </m3e-tabs>
+      <br />
+      <m3e-tabs>
+        <m3e-tab selected for="t1"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 1</m3e-tab>
+        <m3e-tab for="t2" disabled><m3e-icon slot="icon" name="face"></m3e-icon>Disabled tab</m3e-tab>
+        <m3e-tab for="t3"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 3</m3e-tab>
+        <m3e-tab-panel id="t1">Tab 1</m3e-tab-panel>
+        <m3e-tab-panel id="t2">Tab 2</m3e-tab-panel>
+        <m3e-tab-panel id="t3">Tab 3</m3e-tab-panel>
+      </m3e-tabs>
+      <m3e-tabs stretch>
+        <m3e-tab selected for="t4"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 1</m3e-tab>
+        <m3e-tab for="t5"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 2</m3e-tab>
+        <m3e-tab for="t6"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 3</m3e-tab>
+        <m3e-tab-panel id="t4">Tab 1</m3e-tab-panel>
+        <m3e-tab-panel id="t5">Tab 2</m3e-tab-panel>
+        <m3e-tab-panel id="t6">Tab 3</m3e-tab-panel>
+      </m3e-tabs>
+      <m3e-tabs header-position="after">
+        <m3e-tab selected for="t7"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 1</m3e-tab>
+        <m3e-tab for="t8"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 2</m3e-tab>
+        <m3e-tab for="t9"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 3</m3e-tab>
+        <m3e-tab-panel id="t7">Tab 1</m3e-tab-panel>
+        <m3e-tab-panel id="t8">Tab 2</m3e-tab-panel>
+        <m3e-tab-panel id="t9">Tab 3</m3e-tab-panel>
+      </m3e-tabs>
+      <m3e-tabs variant="primary">
+        <m3e-tab selected for="t10"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 1</m3e-tab>
+        <m3e-tab for="t11"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 2</m3e-tab>
+        <m3e-tab for="t12"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 3</m3e-tab>
+        <m3e-tab-panel id="t10">Tab 1</m3e-tab-panel>
+        <m3e-tab-panel id="t11">Tab 2</m3e-tab-panel>
+        <m3e-tab-panel id="t12">Tab 3</m3e-tab-panel>
+      </m3e-tabs>
+      <br />
+      <m3e-tabs variant="primary" header-position="after">
+        <m3e-tab selected for="t13"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 1</m3e-tab>
+        <m3e-tab for="t14"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 2</m3e-tab>
+        <m3e-tab for="t15"><m3e-icon slot="icon" name="face"></m3e-icon>Tab 3</m3e-tab>
+        <m3e-tab-panel id="t13">Tab 1</m3e-tab-panel>
+        <m3e-tab-panel id="t14">Tab 2</m3e-tab-panel>
+        <m3e-tab-panel id="t15">Tab 3</m3e-tab-panel>
+      </m3e-tabs>
+    </m3e-theme>
+  </body>
+</html>

package/dist/css-custom-data.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-tab-font-size",
+      "description": "Font size for tab label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-font-weight",
+      "description": "Font weight for tab label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-line-height",
+      "description": "Line height for tab label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-tracking",
+      "description": "Letter spacing for tab label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-padding-start",
+      "description": "Padding on the inline start of the tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-padding-end",
+      "description": "Padding on the inline end of the tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-focus-ring-shape",
+      "description": "Border radius for the focus ring.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-selected-color",
+      "description": "Text color for selected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-selected-container-hover-color",
+      "description": "Hover state-layer color for selected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-selected-container-focus-color",
+      "description": "Focus state-layer color for selected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-selected-ripple-color",
+      "description": "Ripple color for selected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-unselected-color",
+      "description": "Text color for unselected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-unselected-container-hover-color",
+      "description": "Hover state-layer color for unselected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-unselected-container-focus-color",
+      "description": "Focus state-layer color for unselected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-unselected-ripple-color",
+      "description": "Ripple color for unselected tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-disabled-color",
+      "description": "Text color for disabled tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-disabled-opacity",
+      "description": "Text opacity for disabled tab.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-spacing",
+      "description": "Column gap between icon and label.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tab-icon-size",
+      "description": "Font size for slotted icon.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-paginator-button-icon-size",
+      "description": "Overrides the icon size for paginator buttons.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-active-indicator-color",
+      "description": "Color of the active tab indicator.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-primary-before-active-indicator-shape",
+      "description": "Border radius for active indicator when header is before and variant is primary.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-primary-after-active-indicator-shape",
+      "description": "Border radius for active indicator when header is after and variant is primary.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-primary-active-indicator-inset",
+      "description": "Inset for primary variant's active indicator.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-primary-active-indicator-thickness",
+      "description": "Thickness for primary variant's active indicator.",
+      "values": []
+    },
+    {
+      "name": "--m3e-tabs-secondary-active-indicator-thickness",
+      "description": "Thickness for secondary variant's active indicator.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}