@loomidev/drawer 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael K. Ocansey
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,396 @@
1
+ # @loomidev/drawer
2
+
3
+ `<loomi-drawer>` — a panel that slides in from the edge of the screen, with configurable
4
+ size, an optional backdrop, and focus management built in.
5
+
6
+ ```bash
7
+ npm install @loomidev/drawer lit
8
+ ```
9
+
10
+ ```js
11
+ import "@loomidev/drawer";
12
+ ```
13
+
14
+ ## Default Drawer
15
+
16
+ Drawers are usually triggered by an action — a button click, say. Every LoomiUI drawer is
17
+ opened and closed by its unique `name`, using the exported `showLoomiDrawer()` /
18
+ `hideLoomiDrawer()` helpers (or the instance methods `show()`/`hide()` if you already have
19
+ a reference to the element).
20
+
21
+ > **Important:** give every drawer on a page a unique `name` — it's how `showLoomiDrawer()`
22
+ > finds the right one.
23
+
24
+ The default drawer slides in from the right, shows a close button, and dismisses on
25
+ backdrop click, outside click, or <kbd>Esc</kbd>.
26
+
27
+ ```html
28
+ <loomi-button onclick="showLoomiDrawer('filters')">Open filters</loomi-button>
29
+
30
+ <loomi-drawer name="filters" title="Filters">
31
+ Filter controls go here.
32
+ </loomi-drawer>
33
+
34
+ <script type="module">
35
+ import { showLoomiDrawer } from "@loomidev/drawer";
36
+ </script>
37
+ ```
38
+
39
+ ## Placements
40
+
41
+ Set `placement` to slide in from any edge. Left/right drawers span the full height and
42
+ size by width; top/bottom drawers span the full width and size by height.
43
+
44
+ ```html
45
+ <loomi-button onclick="showLoomiDrawer('left')">Left</loomi-button>
46
+ <loomi-drawer placement="left" title="Left" name="left">Slides in from the left.</loomi-drawer>
47
+
48
+ <loomi-button onclick="showLoomiDrawer('right')">Right</loomi-button>
49
+ <loomi-drawer placement="right" title="Right" name="right">The default.</loomi-drawer>
50
+
51
+ <loomi-button onclick="showLoomiDrawer('top')">Top</loomi-button>
52
+ <loomi-drawer placement="top" title="Top" name="top">Slides down from the top.</loomi-drawer>
53
+
54
+ <loomi-button onclick="showLoomiDrawer('bottom')">Bottom</loomi-button>
55
+ <loomi-drawer placement="bottom" title="Bottom" name="bottom">Slides up from the bottom.</loomi-drawer>
56
+ ```
57
+
58
+ ## Sizes
59
+
60
+ ```html
61
+ <loomi-button onclick="showLoomiDrawer('small-drawer')">Small</loomi-button>
62
+ <loomi-drawer size="small" title="Small" name="small-drawer">20rem wide.</loomi-drawer>
63
+
64
+ <loomi-button onclick="showLoomiDrawer('medium-drawer')">Medium</loomi-button>
65
+ <loomi-drawer size="medium" title="Medium" name="medium-drawer">28rem wide — the default.</loomi-drawer>
66
+
67
+ <loomi-button onclick="showLoomiDrawer('large-drawer')">Large</loomi-button>
68
+ <loomi-drawer size="large" title="Large" name="large-drawer">36rem wide.</loomi-drawer>
69
+ ```
70
+
71
+ On screens narrower than 30rem, left/right drawers expand to full width regardless of size.
72
+
73
+ ## Scrollable Body
74
+
75
+ The header (title and close button) stays fixed; slotted content scrolls independently
76
+ once it overflows the drawer's height.
77
+
78
+ ```html
79
+ <loomi-button onclick="showLoomiDrawer('long')">Terms</loomi-button>
80
+ <loomi-drawer name="long" title="Terms of service">
81
+ <p>… a few thousand words …</p>
82
+ </loomi-drawer>
83
+ ```
84
+
85
+ ## Backdrop, Outside Click & Escape
86
+
87
+ Three independent toggles control dismissal:
88
+
89
+ - `backdrop` (default `true`) — shows a dimmed overlay behind the panel and blocks
90
+ interaction with the rest of the page while open.
91
+ - `close-on-outside-click` (default `true`) — clicking outside the panel closes it. This
92
+ works even with `backdrop="false"`, since it's just watching for clicks outside the
93
+ panel rather than relying on the backdrop element itself.
94
+ - <kbd>Esc</kbd> always closes the drawer — there's no attribute to turn that off.
95
+
96
+ ```html
97
+ <!-- no dimming overlay, but the rest of the page stays inert because outside clicks
98
+ are still being watched -->
99
+ <loomi-drawer name="quiet" backdrop="false">No backdrop, but outside clicks still close me.</loomi-drawer>
100
+
101
+ <!-- only the close button or Escape can dismiss it -->
102
+ <loomi-drawer name="pinned" close-on-outside-click="false">
103
+ Click outside all you want — only the X (or Escape) closes me.
104
+ </loomi-drawer>
105
+ ```
106
+
107
+ ### Non-Modal Drawers
108
+
109
+ When `backdrop="false"`, the drawer also stops being treated as a modal dialog: it sets
110
+ `aria-modal="false"` and no longer traps <kbd>Tab</kbd> inside the panel, so keyboard users
111
+ can still reach the rest of the page. Use this for a persistent, non-blocking side panel
112
+ rather than a true overlay.
113
+
114
+ ## Custom Animations
115
+
116
+ Every part of the slide animation is overridable through CSS custom properties — no
117
+ rebuild required:
118
+
119
+ | Property | Default |
120
+ | -------------------------------- | -------------------------------- |
121
+ | `--loomi-drawer-duration` | `0.3s` |
122
+ | `--loomi-drawer-easing` | `cubic-bezier(0.32, 0.72, 0, 1)` |
123
+ | `--loomi-drawer-enter-animation` | `loomi-drawer-in-<placement>` |
124
+ | `--loomi-drawer-exit-animation` | `loomi-drawer-out-<placement>` |
125
+
126
+ Override the timing globally:
127
+
128
+ ```css
129
+ :root {
130
+ --loomi-drawer-duration: 0.5s;
131
+ --loomi-drawer-easing: ease-in-out;
132
+ }
133
+ ```
134
+
135
+ Or supply your own `@keyframes` and point the drawer at them for a fully custom motion
136
+ (e.g. a bounce instead of a linear slide). `placement`/`size` aren't reflected as
137
+ attributes, so scope the override with a class or `:root` instead of an attribute
138
+ selector:
139
+
140
+ ```css
141
+ @keyframes my-bounce-in {
142
+ 0% { transform: translateX(100%); }
143
+ 60% { transform: translateX(-1rem); }
144
+ 100% { transform: translateX(0); }
145
+ }
146
+ :root {
147
+ --loomi-drawer-enter-animation: my-bounce-in;
148
+ }
149
+ ```
150
+
151
+ `prefers-reduced-motion: reduce` is honored automatically — the animation still runs (so
152
+ `hide()` resolves promptly) but at a near-instant duration.
153
+
154
+ ## Accessibility
155
+
156
+ For the library-wide baseline, see [Foundations — Accessibility](https://loomiui.com/foundations/#accessibility).
157
+
158
+ ## Responsive behavior
159
+
160
+ For the shared container and viewport rules, see [Foundations — Responsive behavior](https://loomiui.com/foundations/#responsive-behavior).
161
+
162
+ ## Dark mode
163
+
164
+ For theme activation, token overrides, and contrast guidance, see [Foundations — Dark mode](https://loomiui.com/foundations/#dark-mode).
165
+
166
+ ## Attributes
167
+
168
+ | Attribute | Default | Description |
169
+ | ------------------------ | --------- | ------------------------------------------------------------------------- |
170
+ | `name` | _(blank)_ | Unique name for `showLoomiDrawer()` / `hideLoomiDrawer()`. |
171
+ | `title` | _(blank)_ | Header text. |
172
+ | `placement` | `right` | `left` \| `right` \| `top` \| `bottom` |
173
+ | `size` | `medium` | `small` \| `medium` \| `large` |
174
+ | `open` | `false` | Open state (reflected). _(boolean)_ |
175
+ | `show-close-icon` | `true` | Show the header close (X) button. _(boolean)_ |
176
+ | `backdrop` | `true` | Dim the page behind the drawer and block interaction with it. _(boolean)_ |
177
+ | `close-on-outside-click` | `true` | Clicking outside the panel closes it. _(boolean)_ |
178
+ | `prevent-scroll` | `true` | Prevent document scrolling while open. _(boolean)_ |
179
+ | `locale` | _(blank)_ | Locale override for built-in aria labels. |
180
+
181
+ Boolean attributes can be omitted, present, or set to `"false"` in HTML, for example
182
+ `backdrop="false"` or `show-close-icon`.
183
+
184
+ **Methods:** `show()` (void), `hide()` (returns a `Promise<void>` that resolves once the
185
+ close animation finishes and the drawer unmounts).
186
+ **Helpers:** `showLoomiDrawer(name)`, `hideLoomiDrawer(name)`.
187
+
188
+ ## Slots
189
+
190
+ | Slot | Description |
191
+ | ----------- | ------------------------------------ |
192
+ | _(default)_ | Content placed inside the component. |
193
+
194
+ ## Events
195
+
196
+ | Event | Description |
197
+ | ------- | -------------------------------- |
198
+ | `close` | Fired when the component closes. |
199
+ | `open` | Fired when the component opens. |
200
+
201
+ ## Focus Handling
202
+
203
+ Opening a drawer moves focus into it (the close button if shown, otherwise the first
204
+ focusable element, otherwise the panel itself). While `backdrop` is on, <kbd>Tab</kbd> is
205
+ trapped inside the panel; closing it restores focus to whatever was focused before — all
206
+ automatic, no setup needed.
207
+
208
+ ## Full Example
209
+
210
+ ```html
211
+ <loomi-button onclick="showLoomiDrawer('full-drawer')">Open Full Example</loomi-button>
212
+ <loomi-drawer
213
+ name="full-drawer"
214
+ title="Edit profile"
215
+ placement="right"
216
+ size="large"
217
+ show-close-icon
218
+ backdrop
219
+ close-on-outside-click="false"
220
+ style="--loomi-drawer-duration: 0.4s;"
221
+ >
222
+ <p>Only the close button or Escape can dismiss this one.</p>
223
+ </loomi-drawer>
224
+ ```
225
+
226
+ <!-- BEGIN loomi-framework-guide -->
227
+
228
+ ## Framework integration
229
+
230
+ `<loomi-drawer>` is a standard custom element, so the browser can use it in plain HTML, Blade, React, Vue, Angular, Svelte, Astro, and most other frameworks. The important beginner rule is: install the package, import it once before the tag is rendered, then write the Loomi tag in your template.
231
+
232
+ ### Where to run commands
233
+
234
+ Run install commands from the app where you want to use this component. That means the folder that contains that app's `package.json`. Do not run these install commands from `packages/drawer` unless you are editing LoomiUI itself.
235
+
236
+ ```bash
237
+ cd /path/to/your-app
238
+ npm install @loomidev/drawer lit
239
+ ```
240
+
241
+ If you are contributing to LoomiUI itself, first move to the top-level `components` folder. That is where the main `package.json` for all packages lives, and `pnpm --filter ...` commands should be run from there:
242
+
243
+ ```bash
244
+ cd /path/to/your-copy-of-loomiui/components
245
+ pnpm --filter @loomidev/drawer build
246
+ pnpm --filter @loomidev/drawer typecheck
247
+ ```
248
+
249
+ ### Choose your framework
250
+
251
+ <loomi-tabs>
252
+ <loomi-tab label="HTML" active>
253
+
254
+ Use the CDN version for prototypes, documentation pages, or a quick reproduction. The import map tells the browser where to find Lit, which Loomi components use internally.
255
+
256
+ ```html
257
+ <script type="importmap">
258
+ { "imports": { "lit": "https://esm.sh/lit@3.3.3", "lit/": "https://esm.sh/lit@3.3.3/" } }
259
+ </script>
260
+ <script type="module" src="https://esm.sh/@loomidev/drawer"></script>
261
+
262
+ <loomi-drawer name="filters" title="Filters">
263
+ Filter controls go here.
264
+ </loomi-drawer>
265
+ ```
266
+
267
+ </loomi-tab>
268
+ <loomi-tab label="Bundlers and SPAs">
269
+
270
+ In Vite, Webpack, Parcel, Rollup, or a framework build pipeline, install the package and import it once in your main app JavaScript file. After that, you can use the Loomi tag anywhere in your app.
271
+
272
+ ```js
273
+ import "@loomidev/drawer";
274
+ ```
275
+
276
+ </loomi-tab>
277
+ <loomi-tab label="Blade">
278
+
279
+ Run the install command from your Laravel project root, then import the component in `resources/js/app.js`. If your project uses Laravel Vite, `npm run dev` and `npm run build` should also be run from the Laravel project root.
280
+
281
+ ```bash
282
+ cd /path/to/your-laravel-app
283
+ npm install @loomidev/drawer lit
284
+ npm run dev
285
+ ```
286
+
287
+ ```js
288
+ // resources/js/app.js
289
+ import "@loomidev/drawer";
290
+ ```
291
+
292
+ ```blade
293
+ <loomi-drawer name="filters" title="Filters">
294
+ Filter controls go here.
295
+ </loomi-drawer>
296
+ ```
297
+
298
+ </loomi-tab>
299
+ <loomi-tab label="React">
300
+
301
+ React can render Loomi tags directly. If you are on React 18, or if you need to pass arrays, objects, or functions, use a ref and assign those values after the component mounts.
302
+
303
+ ```jsx
304
+ import "@loomidev/drawer";
305
+
306
+ export function LoomiExample() {
307
+ return (
308
+ <loomi-drawer name="filters" title="Filters">
309
+ Filter controls go here.
310
+ </loomi-drawer>
311
+ );
312
+ }
313
+ ```
314
+
315
+ If TypeScript does not recognize the Loomi tag in JSX, add it to your app's JSX type declarations.
316
+
317
+ </loomi-tab>
318
+ <loomi-tab label="Vue">
319
+
320
+ Import the package in the component that uses it, or once in your main Vue file. Vue templates can use Loomi tags directly. For arrays, objects, or functions, pass the value as a JavaScript property instead of as plain text.
321
+
322
+ ```vue
323
+ <script setup>
324
+ import "@loomidev/drawer";
325
+ </script>
326
+
327
+ <template>
328
+ <loomi-drawer name="filters" title="Filters">
329
+ Filter controls go here.
330
+ </loomi-drawer>
331
+ </template>
332
+ ```
333
+
334
+ If Vue warns that the tag is an unknown component, configure `compilerOptions.isCustomElement` for tags that start with `loomi-` in your Vite or Vue config.
335
+
336
+ </loomi-tab>
337
+ <loomi-tab label="Angular">
338
+
339
+ Import the package once and tell Angular to allow custom HTML tags with `CUSTOM_ELEMENTS_SCHEMA`. For NgModule apps, add the schema to the module instead of the standalone component.
340
+
341
+ ```ts
342
+ // app.component.ts
343
+ import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
344
+ import "@loomidev/drawer";
345
+
346
+ @Component({
347
+ selector: "app-root",
348
+ standalone: true,
349
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
350
+ template: `
351
+ <loomi-drawer name="filters" title="Filters">
352
+ Filter controls go here.
353
+ </loomi-drawer>
354
+ `,
355
+ })
356
+ export class AppComponent {}
357
+ ```
358
+
359
+ </loomi-tab>
360
+ <loomi-tab label="Svelte / Astro">
361
+
362
+ Svelte can import the package inside a component script. Astro can import it in the frontmatter of the page or layout where the tag appears.
363
+
364
+ ```svelte
365
+ <script>
366
+ import "@loomidev/drawer";
367
+ </script>
368
+
369
+ <loomi-drawer name="filters" title="Filters">
370
+ Filter controls go here.
371
+ </loomi-drawer>
372
+ ```
373
+
374
+ ```astro
375
+ ---
376
+ import "@loomidev/drawer";
377
+ ---
378
+
379
+ <loomi-drawer name="filters" title="Filters">
380
+ Filter controls go here.
381
+ </loomi-drawer>
382
+ ```
383
+
384
+ </loomi-tab>
385
+ </loomi-tabs>
386
+
387
+ ### Server-side rendering notes
388
+
389
+ Frameworks such as Next.js, Nuxt, SvelteKit, and Astro sometimes render HTML on the server before browser-only code runs. If your framework complains, move the Loomi import to client-side code. In Next.js, that usually means a component with `"use client"`; in Nuxt, it often means a `.client.ts` plugin.
390
+
391
+ <!-- END loomi-framework-guide -->
392
+
393
+ ## Dependencies
394
+
395
+ - `@loomidev/core`
396
+ - `@loomidev/icon`