@m3e/slide-group 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,116 @@
+# @m3e/slide-group
+
+The `m3e-slide-group` component presents directional pagination controls for navigating overflowing content. It orchestrates scrollable layouts with expressive slot-based icons and adaptive orientation, revealing navigation affordances only when content exceeds a defined threshold. It supports both horizontal and vertical flows, and encodes accessibility through customizable labels and interaction states.
+
+> **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/slide-group
+```
+
+## 💻 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/slide-group`, 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/slide-group/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/slide-group/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/slide-group/dist/index.js"></script>
+```
+
+You also need a module script for `@m3e/icon-button` due to it being a dependency.
+
+```html
+<script type="module" src="/node_modules/@m3e/icon-button/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-slide-group` — Presents pagination controls used to scroll overflowing content.
+
+## 🧪 Examples
+
+- The following example illustrates a horizontally scrollable group of items with directional pagination buttons.
+  The scroll controls appear when content exceeds the `48px` threshold.
+
+```html
+<m3e-slide-group threshold="48">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+  <div>Item 5</div>
+</m3e-slide-group>
+```
+
+## 📖 API Reference
+
+This section details the attributes, slots and CSS custom properties available for the `m3e-slide-group` component.
+
+### ⚙️ Attributes
+
+| Attribute             | Type      | Default           | Description                                                                                        |
+| --------------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------- |
+| `disabled`            | `boolean` | `false`           | Whether scroll buttons are disabled.                                                               |
+| `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.                            |
+| `threshold`           | `number`  | `0`               | A value, in pixels, indicating the scroll threshold at which to begin showing pagination controls. |
+| `vertical`            | `boolean` | `false`           | Whether content is oriented vertically.                                                            |
+
+#### 🧩 Slots
+
+| Slot        | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| _(default)_ | Renders the content to paginate.                     |
+| `next-icon` | Renders the icon to present for the next button.     |
+| `prev-icon` | Renders the icon to present for the previous button. |
+
+### 🎛️ CSS Custom Properties
+
+| Property                             | Description                                                                   |
+| ------------------------------------ | ----------------------------------------------------------------------------- |
+| `--m3e-slide-group-button-icon-size` | Sets icon size for scroll buttons; overrides default small icon size.         |
+| `--m3e-slide-group-button-size`      | Defines scroll button size; used for width (horizontal) or height (vertical). |
+| `--m3e-slide-group-divider-top`      | Adds top border to content container for visual separation.                   |
+| `--m3e-slide-group-divider-bottom`   | Adds bottom border to content container for visual separation.                |
+
+## 🤝 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/dist/css-custom-data.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-slide-group-button-icon-size",
+      "description": "Sets icon size for scroll buttons; overrides default small icon size.",
+      "values": []
+    },
+    {
+      "name": "--m3e-slide-group-button-size",
+      "description": "Defines scroll button size; used for width (horizontal) or height (vertical).",
+      "values": []
+    },
+    {
+      "name": "--m3e-slide-group-divider-top",
+      "description": "Adds top border to content container for visual separation.",
+      "values": []
+    },
+    {
+      "name": "--m3e-slide-group-divider-bottom",
+      "description": "Adds bottom border to content container for visual separation.",
+      "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": "\"./SlideGroupElement\""
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/SlideGroupElement.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "M3eSlideGroupElement",
+          "cssProperties": [
+            {
+              "description": "Sets icon size for scroll buttons; overrides default small icon size.",
+              "name": "--m3e-slide-group-button-icon-size"
+            },
+            {
+              "description": "Defines scroll button size; used for width (horizontal) or height (vertical).",
+              "name": "--m3e-slide-group-button-size"
+            },
+            {
+              "description": "Adds top border to content container for visual separation.",
+              "name": "--m3e-slide-group-divider-top"
+            },
+            {
+              "description": "Adds bottom border to content container for visual separation.",
+              "name": "--m3e-slide-group-divider-bottom"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Renders the content to paginate.",
+              "name": ""
+            },
+            {
+              "description": "Renders the icon to present for the next button.",
+              "name": "next-icon"
+            },
+            {
+              "description": "Renders the icon to present for the previous button.",
+              "name": "prev-icon"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "#resizeController",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new ResizeController(this, { target: null, callback: () => this._updatePaging(), })"
+            },
+            {
+              "kind": "field",
+              "name": "_canPage",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_canPageStart",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_canPageEnd",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether scroll buttons are disabled.",
+              "attribute": "disabled",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "vertical",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether content is oriented vertically.",
+              "attribute": "vertical",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "threshold",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "A value, in pixels, indicating the scroll threshold at which to begin showing pagination controls.",
+              "attribute": "threshold"
+            },
+            {
+              "kind": "field",
+              "name": "previousPageLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Previous page\"",
+              "description": "The accessible label given to the button used to move to the previous page.",
+              "attribute": "previous-page-label"
+            },
+            {
+              "kind": "field",
+              "name": "nextPageLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Next page\"",
+              "description": "The accessible label given to the button used to move to the next page.",
+              "attribute": "next-page-label"
+            },
+            {
+              "kind": "method",
+              "name": "#pageStart",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "#pageEnd",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_updatePaging",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "description": "Whether scroll buttons are disabled.",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "disabled"
+            },
+            {
+              "description": "The accessible label given to the button used to move to the next page.",
+              "name": "next-page-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Next page\"",
+              "fieldName": "nextPageLabel"
+            },
+            {
+              "description": "The accessible label given to the button used to move to the previous page.",
+              "name": "previous-page-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Previous page\"",
+              "fieldName": "previousPageLabel"
+            },
+            {
+              "description": "A value, in pixels, indicating the scroll threshold at which to begin showing pagination controls.",
+              "name": "threshold",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "fieldName": "threshold"
+            },
+            {
+              "description": "Whether content is oriented vertically.",
+              "name": "vertical",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "vertical"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "Role",
+              "package": "@m3e/core"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "m3e-slide-group",
+          "customElement": true,
+          "summary": "Presents pagination controls used to scroll overflowing content."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "M3eSlideGroupElement",
+          "declaration": {
+            "name": "M3eSlideGroupElement",
+            "module": "src/SlideGroupElement.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "m3e-slide-group",
+          "declaration": {
+            "name": "M3eSlideGroupElement",
+            "module": "src/SlideGroupElement.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/html-custom-data.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-html-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "tags": [
+    {
+      "name": "m3e-slide-group",
+      "description": "Presents pagination controls used to scroll overflowing content.\n---\n\n\n### **Slots:**\n - _default_ - Renders the content to paginate.\n- **next-icon** - Renders the icon to present for the next button.\n- **prev-icon** - Renders the icon to present for the previous button.\n\n### **CSS Properties:**\n - **--m3e-slide-group-button-icon-size** - Sets icon size for scroll buttons; overrides default small icon size. _(default: undefined)_\n- **--m3e-slide-group-button-size** - Defines scroll button size; used for width (horizontal) or height (vertical). _(default: undefined)_\n- **--m3e-slide-group-divider-top** - Adds top border to content container for visual separation. _(default: undefined)_\n- **--m3e-slide-group-divider-bottom** - Adds bottom border to content container for visual separation. _(default: undefined)_",
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether scroll buttons are disabled.",
+          "values": []
+        },
+        {
+          "name": "next-page-label",
+          "description": "The accessible label given to the button used to move to the next page.",
+          "values": []
+        },
+        {
+          "name": "previous-page-label",
+          "description": "The accessible label given to the button used to move to the previous page.",
+          "values": []
+        },
+        {
+          "name": "threshold",
+          "description": "A value, in pixels, indicating the scroll threshold at which to begin showing pagination controls.",
+          "values": []
+        },
+        {
+          "name": "vertical",
+          "description": "Whether content is oriented vertically.",
+          "values": []
+        }
+      ],
+      "references": []
+    }
+  ]
+}