@loomidev/floating-panel 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,389 @@
1
+ # @loomidev/floating-panel
2
+
3
+ `<loomi-floating-panel>` — a draggable, resizable panel that floats above the page,
4
+ unanchored to any trigger. Think devtools panel, help widget, or a chat window you can
5
+ drag around and resize.
6
+
7
+ ```bash
8
+ npm install @loomidev/floating-panel lit
9
+ ```
10
+
11
+ ```js
12
+ import "@loomidev/floating-panel";
13
+ ```
14
+
15
+ ## Basic Usage
16
+
17
+ Every panel is opened and closed by its unique `name`, using the exported
18
+ `showLoomiFloatingPanel()` / `hideLoomiFloatingPanel()` helpers (or the instance methods
19
+ `show()`/`hide()` if you already have a reference to the element). With no `top`/`left`
20
+ attribute, it opens centered in the viewport.
21
+
22
+ ```html
23
+ <loomi-button onclick="showLoomiFloatingPanel('help')">Open help</loomi-button>
24
+
25
+ <loomi-floating-panel name="help" title="Need a hand?">
26
+ Drag the header to move me, or grab an edge/corner to resize.
27
+ </loomi-floating-panel>
28
+
29
+ <script type="module">
30
+ import { showLoomiFloatingPanel } from "@loomidev/floating-panel";
31
+ </script>
32
+ ```
33
+
34
+ ## Position & Size
35
+
36
+ `top`/`left` and `width`/`height` accept any CSS length and set the panel's initial rect.
37
+ Once the user drags or resizes it, the panel tracks its own pixel position from then on.
38
+
39
+ ```html
40
+ <loomi-floating-panel
41
+ name="notes"
42
+ title="Notes"
43
+ top="4rem"
44
+ left="4rem"
45
+ width="20rem"
46
+ height="16rem"
47
+ >
48
+ Opens pinned to the top-left instead of centered.
49
+ </loomi-floating-panel>
50
+ ```
51
+
52
+ `min-width`/`min-height`/`max-width`/`max-height` (plain pixel numbers) constrain
53
+ resizing. `bounded` (default `true`) keeps the panel's edges inside the viewport while
54
+ dragging or resizing; set `bounded="false"` to allow it to move fully off-screen.
55
+
56
+ ## Dragging & Resizing
57
+
58
+ Both are on by default. `no-drag` disables moving the panel by its header; `resizable="false"`
59
+ removes all eight resize handles.
60
+
61
+ ```html
62
+ <loomi-floating-panel name="pinned" title="Pinned" no-drag resizable="false">
63
+ Fixed in place — no header drag, no resize handles.
64
+ </loomi-floating-panel>
65
+ ```
66
+
67
+ The header and each resize handle are keyboard-operable: focus the header and press the
68
+ arrow keys to move the panel; focus a resize handle and press the arrow keys to resize
69
+ from that edge/corner. Hold <kbd>Shift</kbd> for a bigger step.
70
+
71
+ ## Minimize, Maximize & Drag Handle
72
+
73
+ `minimize` and `maximize` add header buttons that toggle collapsing the panel to just its
74
+ title bar, or expanding it to fill the viewport — both off by default. `drag-handle`
75
+ restricts dragging to a small grip icon instead of the whole header, useful once you add
76
+ your own interactive content there.
77
+
78
+ ```html
79
+ <loomi-floating-panel name="window" title="Window-like" minimize maximize drag-handle>
80
+ Minimize/maximize buttons appear in the header; only the grip icon drags.
81
+ </loomi-floating-panel>
82
+ ```
83
+
84
+ Toggling either fires `loomi-minimize`/`loomi-maximize`; maximizing clears `minimized` and
85
+ vice versa, since a panel can't be both at once. Restoring from maximized snaps back to
86
+ the exact rect the panel had before — dragging and resizing are disabled while maximized
87
+ (and resizing while minimized, since there's no body to resize into). Double-clicking the
88
+ header also toggles maximize, when `maximize` is enabled.
89
+
90
+ ## Multiple Panels & Stacking
91
+
92
+ Open as many panels as you like — clicking or dragging anywhere inside a panel (header,
93
+ body, or a resize handle) brings it to the front of the stack automatically, so the last
94
+ one you touched is always on top.
95
+
96
+ ```html
97
+ <loomi-floating-panel name="a" title="Panel A" top="3rem" left="3rem">First</loomi-floating-panel>
98
+ <loomi-floating-panel name="b" title="Panel B" top="6rem" left="20rem">Second</loomi-floating-panel>
99
+ ```
100
+
101
+ ## Persisting Layout
102
+
103
+ Set `auto-save-id` to remember the panel's position and size in `localStorage` across
104
+ page reloads.
105
+
106
+ ```html
107
+ <loomi-floating-panel name="chat" title="Support chat" auto-save-id="support-chat">
108
+ Comes back exactly where you left it.
109
+ </loomi-floating-panel>
110
+ ```
111
+
112
+ ## Accessibility
113
+
114
+ `<loomi-floating-panel>` renders as `role="dialog"` with `aria-modal="false"` — it never
115
+ traps focus or blocks the rest of the page, since it floats alongside content rather than
116
+ over it. Opening a panel moves focus to its header; closing it restores focus to whatever
117
+ was focused before, and <kbd>Escape</kbd> closes the panel only while focus is inside it
118
+ (so multiple open panels don't all close on one keypress).
119
+
120
+ - <kbd>Tab</kbd> / <kbd>Shift+Tab</kbd> — reach the minimize/maximize/close buttons,
121
+ slotted content, and every resize handle (or the grip, when `drag-handle` is set).
122
+ - Arrow keys on the focused header (or grip) — move the panel; hold <kbd>Shift</kbd> for
123
+ a 10px step.
124
+ - Arrow keys on a focused resize handle — resize from that edge/corner; hold
125
+ <kbd>Shift</kbd> for a 10px step.
126
+ - <kbd>Escape</kbd> — close, while focus is inside the panel.
127
+ - Visible `:focus-visible` rings on the header, grip, header buttons, and resize handles.
128
+
129
+ For the library-wide baseline, see [Foundations — Accessibility](https://loomiui.com/foundations/#accessibility).
130
+
131
+ ## Responsive behavior
132
+
133
+ The panel caps itself to `100dvw`/`100dvh` so it can never overflow the viewport even if
134
+ `width`/`height` are set larger than the screen, and `bounded` (on by default) keeps its
135
+ edges from being dragged or resized outside the viewport. On narrow viewports the header
136
+ and body padding tighten below a `480px` breakpoint.
137
+
138
+ For the shared container and viewport rules, see [Foundations — Responsive behavior](https://loomiui.com/foundations/#responsive-behavior).
139
+
140
+ ## Dark mode
141
+
142
+ Uses semantic `--loomi-surface`, `--loomi-surface-border`, `--loomi-text`, and
143
+ `--loomi-text-secondary`/`--loomi-text-faint` tokens instead of hard-coded colors. Add
144
+ `.dark` to your app root with `@loomidev/theme-switcher`, or provide your own token
145
+ overrides, and the panel inherits the dark-mode values through its shadow DOM.
146
+
147
+ For theme activation, token overrides, and contrast guidance, see [Foundations — Dark mode](https://loomiui.com/foundations/#dark-mode).
148
+
149
+ ## Attributes
150
+
151
+ | Attribute | Default | Description |
152
+ | ----------------- | ------------- | ----------------------------------------------------------------------------------- |
153
+ | `name` | _(blank)_ | Unique name for `showLoomiFloatingPanel()` / `hideLoomiFloatingPanel()`. |
154
+ | `title` | _(blank)_ | Header text. |
155
+ | `open` | `false` | Open state (reflected). _(boolean)_ |
156
+ | `show-close-icon` | `true` | Show the header close (X) button. _(boolean)_ |
157
+ | `resizable` | `true` | Show the eight edge/corner resize handles. _(boolean)_ |
158
+ | `no-drag` | `false` | Disable moving the panel by its header. _(boolean)_ |
159
+ | `bounded` | `true` | Keep the panel's edges inside the viewport while dragging/resizing. _(boolean)_ |
160
+ | `minimize` | `false` | Show a header button that collapses the panel to its title bar. _(boolean)_ |
161
+ | `maximize` | `false` | Show a header button that expands the panel to fill the viewport. _(boolean)_ |
162
+ | `drag-handle` | `false` | Restrict dragging to a dedicated grip icon instead of the whole header. _(boolean)_ |
163
+ | `minimized` | `false` | Current collapsed state (reflected); settable up front too. _(boolean)_ |
164
+ | `maximized` | `false` | Current fill-the-viewport state (reflected); settable up front too. _(boolean)_ |
165
+ | `top` | _(blank)_ | Initial vertical position, any CSS length. Unset opens centered. |
166
+ | `left` | _(blank)_ | Initial horizontal position, any CSS length. Unset opens centered. |
167
+ | `width` | _(blank)_ | Initial width, any CSS length. Unset falls back to `22rem`. |
168
+ | `height` | _(blank)_ | Initial height, any CSS length. Unset falls back to `26rem`. |
169
+ | `min-width` | `220` | Minimum width in pixels while resizing. _(number)_ |
170
+ | `min-height` | `140` | Minimum height in pixels while resizing. _(number)_ |
171
+ | `max-width` | _(unbounded)_ | Maximum width in pixels while resizing. _(number)_ |
172
+ | `max-height` | _(unbounded)_ | Maximum height in pixels while resizing. _(number)_ |
173
+ | `auto-save-id` | _(blank)_ | Persist position/size to `localStorage` under this key. |
174
+ | `locale` | _(blank)_ | Locale override for built-in aria labels. |
175
+
176
+ Boolean attributes can be omitted, present, or set to `"false"` in HTML, for example
177
+ `resizable="false"` or `no-drag`.
178
+
179
+ **Methods:** `show()`, `hide()` (both void).
180
+ **Helpers:** `showLoomiFloatingPanel(name)`, `hideLoomiFloatingPanel(name)`.
181
+
182
+ ## Slots
183
+
184
+ | Slot | Description |
185
+ | ----------- | ------------------------------------ |
186
+ | _(default)_ | Content placed inside the component. |
187
+
188
+ ## Events
189
+
190
+ ```js
191
+ const panel = document.querySelector('loomi-floating-panel[name="help"]');
192
+ panel.addEventListener("open", () => console.log("opened"));
193
+ panel.addEventListener("close", () => console.log("closed"));
194
+ panel.addEventListener("loomi-drag", (e) => console.log("moved to", e.detail)); // { top, left }
195
+ panel.addEventListener("loomi-resize", (e) => console.log("resized to", e.detail)); // { top, left, width, height }
196
+ panel.addEventListener("loomi-minimize", (e) => console.log("minimized:", e.detail.minimized));
197
+ panel.addEventListener("loomi-maximize", (e) => console.log("maximized:", e.detail.maximized));
198
+ ```
199
+
200
+ ## Full Example
201
+
202
+ ```html
203
+ <loomi-button onclick="showLoomiFloatingPanel('full-panel')">Open Full Example</loomi-button>
204
+ <loomi-floating-panel
205
+ name="full-panel"
206
+ title="Support chat"
207
+ top="5rem"
208
+ left="5rem"
209
+ width="24rem"
210
+ height="28rem"
211
+ min-width="260"
212
+ min-height="180"
213
+ auto-save-id="support-chat"
214
+ >
215
+ <p>Drag me, resize me, reload the page — I'll come back right here.</p>
216
+ </loomi-floating-panel>
217
+ ```
218
+
219
+ <!-- BEGIN loomi-framework-guide -->
220
+
221
+ ## Framework integration
222
+
223
+ `<loomi-floating-panel>` 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.
224
+
225
+ ### Where to run commands
226
+
227
+ 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/floating-panel` unless you are editing LoomiUI itself.
228
+
229
+ ```bash
230
+ cd /path/to/your-app
231
+ npm install @loomidev/floating-panel lit
232
+ ```
233
+
234
+ 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:
235
+
236
+ ```bash
237
+ cd /path/to/your-copy-of-loomiui/components
238
+ pnpm --filter @loomidev/floating-panel build
239
+ pnpm --filter @loomidev/floating-panel typecheck
240
+ ```
241
+
242
+ ### Choose your framework
243
+
244
+ <loomi-tabs>
245
+ <loomi-tab label="HTML" active>
246
+
247
+ 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.
248
+
249
+ ```html
250
+ <script type="importmap">
251
+ { "imports": { "lit": "https://esm.sh/lit@3.3.3", "lit/": "https://esm.sh/lit@3.3.3/" } }
252
+ </script>
253
+ <script type="module" src="https://esm.sh/@loomidev/floating-panel"></script>
254
+
255
+ <loomi-floating-panel name="help" title="Need a hand?">
256
+ Drag the header to move me, or grab an edge/corner to resize.
257
+ </loomi-floating-panel>
258
+ ```
259
+
260
+ </loomi-tab>
261
+ <loomi-tab label="Bundlers and SPAs">
262
+
263
+ 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.
264
+
265
+ ```js
266
+ import "@loomidev/floating-panel";
267
+ ```
268
+
269
+ </loomi-tab>
270
+ <loomi-tab label="Blade">
271
+
272
+ 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.
273
+
274
+ ```bash
275
+ cd /path/to/your-laravel-app
276
+ npm install @loomidev/floating-panel lit
277
+ npm run dev
278
+ ```
279
+
280
+ ```js
281
+ // resources/js/app.js
282
+ import "@loomidev/floating-panel";
283
+ ```
284
+
285
+ ```blade
286
+ <loomi-floating-panel name="help" title="Need a hand?">
287
+ Drag the header to move me, or grab an edge/corner to resize.
288
+ </loomi-floating-panel>
289
+ ```
290
+
291
+ </loomi-tab>
292
+ <loomi-tab label="React">
293
+
294
+ 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.
295
+
296
+ ```jsx
297
+ import "@loomidev/floating-panel";
298
+
299
+ export function LoomiExample() {
300
+ return (
301
+ <loomi-floating-panel name="help" title="Need a hand?">
302
+ Drag the header to move me, or grab an edge/corner to resize.
303
+ </loomi-floating-panel>
304
+ );
305
+ }
306
+ ```
307
+
308
+ If TypeScript does not recognize the Loomi tag in JSX, add it to your app's JSX type declarations.
309
+
310
+ </loomi-tab>
311
+ <loomi-tab label="Vue">
312
+
313
+ 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.
314
+
315
+ ```vue
316
+ <script setup>
317
+ import "@loomidev/floating-panel";
318
+ </script>
319
+
320
+ <template>
321
+ <loomi-floating-panel name="help" title="Need a hand?">
322
+ Drag the header to move me, or grab an edge/corner to resize.
323
+ </loomi-floating-panel>
324
+ </template>
325
+ ```
326
+
327
+ 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.
328
+
329
+ </loomi-tab>
330
+ <loomi-tab label="Angular">
331
+
332
+ 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.
333
+
334
+ ```ts
335
+ // app.component.ts
336
+ import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
337
+ import "@loomidev/floating-panel";
338
+
339
+ @Component({
340
+ selector: "app-root",
341
+ standalone: true,
342
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
343
+ template: `
344
+ <loomi-floating-panel name="help" title="Need a hand?">
345
+ Drag the header to move me, or grab an edge/corner to resize.
346
+ </loomi-floating-panel>
347
+ `,
348
+ })
349
+ export class AppComponent {}
350
+ ```
351
+
352
+ </loomi-tab>
353
+ <loomi-tab label="Svelte / Astro">
354
+
355
+ 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.
356
+
357
+ ```svelte
358
+ <script>
359
+ import "@loomidev/floating-panel";
360
+ </script>
361
+
362
+ <loomi-floating-panel name="help" title="Need a hand?">
363
+ Drag the header to move me, or grab an edge/corner to resize.
364
+ </loomi-floating-panel>
365
+ ```
366
+
367
+ ```astro
368
+ ---
369
+ import "@loomidev/floating-panel";
370
+ ---
371
+
372
+ <loomi-floating-panel name="help" title="Need a hand?">
373
+ Drag the header to move me, or grab an edge/corner to resize.
374
+ </loomi-floating-panel>
375
+ ```
376
+
377
+ </loomi-tab>
378
+ </loomi-tabs>
379
+
380
+ ### Server-side rendering notes
381
+
382
+ 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.
383
+
384
+ <!-- END loomi-framework-guide -->
385
+
386
+ ## Dependencies
387
+
388
+ - `@loomidev/core`
389
+ - `@loomidev/icon`