@m3e/drawer-container 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,139 @@
+# @m3e/drawer-container
+
+The `m3e-drawer-container` component provides a responsive layout container for managing one or two sliding drawers alongside main content. It supports multiple drawer modes (`over`, `push`, `side`, and `auto`), adapts to breakpoint size, and encodes spatial hierarchy, motion transitions, and accessibility semantics for modal, dismissible, and permanent navigation.
+
+> **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/drawer-container
+```
+
+## 💻 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/drawer-container`, 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/drawer-container/dist/html-custom-data.json"],
+  "css.customData": ["./node_modules/@m3e/drawer-container/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/drawer-container/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/layout": "/node_modules/@m3e/core/dist/layout.js"
+    }
+  }
+</script>
+```
+
+> For production, use index.min.js and layout.min.js for faster load times.
+
+## 🗂️ Elements
+
+- `m3e-drawer-container` — A container for one or two sliding drawers.
+- `m3e-drawer-toggle` — An element, nested within a clickable element, used to toggle the opened state of a drawer.
+
+## 🧪 Examples
+
+The following example illustrates a typical drawer layout.
+
+```html
+<m3e-drawer-container>
+  <nav slot="start">
+    <!-- Start drawer content -->
+  </nav>
+  <main>
+    <!-- Main content -->
+  </main>
+  <aside slot="end">
+    <!-- End drawer content -->
+  </aside>
+</m3e-drawer-container>
+```
+
+The next example illustrates the use of a `m3e-drawer-toggle`, nested inside a `m3e-icon-button` component, which toggles the open state of the start drawer.
+
+```html
+<m3e-icon-button slot="leading-icon" aria-label="Menu" toggle selected>
+  <m3e-drawer-toggle for="startDrawer"></m3e-drawer-toggle>
+  <m3e-icon name="menu"></m3e-icon>
+  <m3e-icon slot="selected" name="menu_open"></m3e-icon>
+</m3e-icon-button>
+
+<m3e-drawer-container start>
+  <nav slot="start" id="startDrawer" aria-label="Navigation">
+    <!-- Start drawer content -->
+  </nav>
+  <!-- Container content -->
+</m3e-drawer-container>
+```
+
+## 📖 API Reference
+
+This section details the attributes and CSS custom properties available for the `m3e-drawer-container` component.
+
+### ⚙️ Attributes
+
+| Attribute       | Type                                   | Default  | Description                                                                               |
+| --------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `start`         | `boolean`                              | `false`  | Whether the start drawer is open.                                                         |
+| `start-mode`    | `"over" \| "push" \| "side" \| "auto"` | `"side"` | The behavior mode of the start drawer. Supports `over`, `push`, `side`, and `auto` modes. |
+| `start-divider` | `boolean`                              | `false`  | Whether to show a divider between the start drawer and content for `side` mode.           |
+| `end`           | `boolean`                              | `false`  | Whether the end drawer is open.                                                           |
+| `end-mode`      | `"over" \| "push" \| "side" \| "auto"` | `"side"` | The behavior mode of the end drawer. Supports `over`, `push`, `side`, and `auto` modes.   |
+| `end-divider`   | `boolean`                              | `false`  | Whether to show a divider between the end drawer and content for `side` mode.             |
+
+### 🧩 Slots
+
+| Slot        | Description               |
+| ----------- | ------------------------- |
+| _(default)_ | Renders the main content. |
+| `start`     | Renders the start drawer. |
+| `end`       | Renders the end drawer.   |
+
+### 🎛️ CSS Custom Properties
+
+| Property                               | Description                                                   |
+| -------------------------------------- | ------------------------------------------------------------- |
+| `--m3e-drawer-container-color`         | The background color of the drawer container.                 |
+| `--m3e-drawer-container-elevation`     | The elevation level of the drawer container.                  |
+| `--m3e-drawer-container-width`         | The width of the drawer container.                            |
+| `--m3e-drawer-container-scrim-opacity` | The opacity of the scrim behind the drawer.                   |
+| `--m3e-modal-drawer-start-shape`       | The shape of the drawer’s start edge (typically left in LTR). |
+| `--m3e-modal-drawer-end-shape`         | The shape of the drawer’s end edge (typically right in LTR).  |
+| `--m3e-modal-drawer-container-color`   | The background color of the modal drawer container.           |
+| `--m3e-modal-drawer-elevation`         | The elevation level of the modal drawer container.            |
+| `--m3e-drawer-divider-color`           | The color of the divider between drawer sections.             |
+| `--m3e-drawer-divider-thickness`       | The thickness of the divider line.                            |
+
+## 🤝 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,88 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Drawer Container for M3E</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Drawer Container 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="../../app-bar/dist/index.min.js"></script>
+    <script type="module" src="../../icon-button/dist/index.min.js"></script>
+    <script type="module" src="../../icon/dist/index.min.js"></script>
+    <script type="module" src="../../nav-menu/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 {
+        margin: unset;
+        font-family: "Roboto";
+        display: flex;
+        flex-direction: column;
+        height: 100vh;
+        overflow: hidden;
+      }
+      m3e-app-bar {
+        flex: none;
+      }
+      m3e-drawer-container {
+        flex: 1 1 auto;
+      }
+    </style>
+  </head>
+  <body>
+    <m3e-theme strong-focus>
+      <m3e-app-bar>
+        <m3e-icon-button slot="leading-icon" aria-label="Menu" toggle>
+          <m3e-icon name="menu"></m3e-icon>
+          <m3e-icon slot="selected" name="menu_open"></m3e-icon>
+          <m3e-drawer-toggle for="startDrawer"></m3e-drawer-toggle>
+        </m3e-icon-button>
+        <span slot="title">App title</span>
+      </m3e-app-bar>
+      <m3e-drawer-container start end start-mode="auto" end-mode="auto" end-divider>
+        <m3e-nav-menu id="startDrawer" slot="start">
+          <m3e-nav-menu-item open>
+            <m3e-icon slot="icon" name="rocket_launch"></m3e-icon>
+            <span slot="label">Getting Started</span>
+            <m3e-nav-menu-item>
+              <m3e-icon slot="icon" name="widgets"></m3e-icon>
+              <span slot="label">Overview</span>
+            </m3e-nav-menu-item>
+            <m3e-nav-menu-item>
+              <m3e-icon slot="icon" name="package_2"></m3e-icon>
+              <span slot="label">Installation</span>
+            </m3e-nav-menu-item>
+          </m3e-nav-menu-item>
+          <m3e-nav-menu-item>
+            <span slot="label">Actions</span>
+            <m3e-nav-menu-item><span slot="label">Button</span></m3e-nav-menu-item>
+            <m3e-nav-menu-item><span slot="label">Icon</span></m3e-nav-menu-item>
+            <m3e-nav-menu-item><span slot="label">Icon Button</span></m3e-nav-menu-item>
+          </m3e-nav-menu-item>
+        </m3e-nav-menu>
+        <aside slot="end">Right-side content</aside>
+        <div>Main content</div>
+      </m3e-drawer-container>
+    </m3e-theme>
+  </body>
+</html>

package/dist/css-custom-data.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [
+    {
+      "name": "--m3e-drawer-container-color",
+      "description": "The background color of the drawer container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-drawer-container-elevation",
+      "description": "The elevation level of the drawer container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-drawer-container-width",
+      "description": "The width of the drawer container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-drawer-container-scrim-opacity",
+      "description": "The opacity of the scrim behind the drawer.",
+      "values": []
+    },
+    {
+      "name": "--m3e-modal-drawer-start-shape",
+      "description": "The shape of the drawer’s start edge (typically left in LTR).",
+      "values": []
+    },
+    {
+      "name": "--m3e-modal-drawer-end-shape",
+      "description": "The shape of the drawer’s end edge (typically right in LTR).",
+      "values": []
+    },
+    {
+      "name": "--m3e-modal-drawer-container-color",
+      "description": "The background color of the modal drawer container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-modal-drawer-elevation",
+      "description": "The elevation level of the modal drawer container.",
+      "values": []
+    },
+    {
+      "name": "--m3e-drawer-divider-color",
+      "description": "The color of the divider between drawer sections.",
+      "values": []
+    },
+    {
+      "name": "--m3e-drawer-divider-thickness",
+      "description": "The thickness of the divider line.",
+      "values": []
+    }
+  ],
+  "pseudoElements": []
+}