@corndev/ui-overlays 0.0.0-stage → 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corndog Development LLC
+
+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

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+<!-- Generated by scripts/generate-readmes.js. Edit the registry or that script, not this file. -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @corndev/ui-overlays
+
+Overlay components: Modal, Drawer, Accordion, Tooltip, Popover, Menu.
+
+## Install
+
+```bash
+npm install @corndev/ui-overlays
+```
+
+## Use
+
+```js
+import { createModal } from '@corndev/ui-overlays';
+import '@corndev/ui-overlays/styles';
+```
+
+## Styles
+
+The stylesheet ships with the package and is imported separately, so a page can use the classes with no JavaScript:
+
+```js
+import '@corndev/ui-overlays/styles';
+```
+
+## Components
+
+- [Modal](https://cornui.com/components/modal) — Dialog overlay with focus trap, backdrop, and Escape to close.
+- [Drawer](https://cornui.com/components/drawer) — Slide-in panel from left or right with focus trap.
+- [Accordion](https://cornui.com/components/accordion) — Collapsible sections. Vanilla expects [data-accordion-item][data-accordion-trigger] and [data-accordion-item][data-accordion-panel] in markup; React composes Accordion.Item children.
+- [Tooltip](https://cornui.com/components/tooltip) — Small label shown on hover/focus. Auto-flips when near viewport edge.
+- [Popover](https://cornui.com/components/popover) — Floating panel anchored to a trigger. Auto-flips when near viewport edge.
+- [Menu](https://cornui.com/components/menu) — Dropdown menu anchored to a trigger, with keyboard navigation (arrows/Home/End/Escape) and menu roles. Vanilla takes an items array; React composes MenuItem/MenuSeparator children.
+
+## Documentation
+
+- [Component documentation](https://cornui.com/components/modal)
+- [Installing](https://cornui.com/installation)
+- [Theming](https://cornui.com/theming)
+- [llms.txt](https://cornui.com/llms.txt) — the whole API in one file, for coding agents
+
+## Licence
+
+MIT © Corndog Development LLC. See [LICENSE](https://gitlab.com/corn-dev/corn-ui/-/blob/master/LICENSE).

package/dist/components/accordion/accordion.css

@@ -0,0 +1,109 @@
+/* === Accordion Container === */
+.corn-accordion {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--corn-border-light);
+  border-radius: var(--corn-radius-md);
+  overflow: hidden;
+}
+
+/* === Trigger (header button) === */
+.corn-accordion-trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: var(--corn-spacing-md) var(--corn-spacing-lg);
+  background: var(--corn-bg-primary);
+  border: none;
+  border-bottom: 1px solid var(--corn-border-light);
+  cursor: pointer;
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-base);
+  font-weight: var(--corn-font-weight-medium);
+  color: var(--corn-text-primary);
+  text-align: left;
+  line-height: var(--corn-line-height);
+  transition: background-color var(--corn-transition-fast);
+  gap: var(--corn-spacing-sm);
+}
+
+.corn-accordion-trigger:hover {
+  background: var(--corn-bg-secondary);
+}
+
+.corn-accordion-trigger:focus-visible {
+  outline: 2px solid var(--corn-primary);
+  outline-offset: -2px;
+}
+
+/* Last trigger gets no border when closed */
+.corn-accordion-trigger:last-of-type {
+  border-bottom: none;
+}
+
+/* Chevron icon via ::after */
+.corn-accordion-trigger::after {
+  content: '';
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-right: 2px solid currentColor;
+  border-bottom: 2px solid currentColor;
+  transform: rotate(45deg);
+  transition: transform var(--corn-transition-base);
+  flex-shrink: 0;
+}
+
+.corn-accordion-trigger[data-open]::after {
+  transform: rotate(-135deg);
+}
+
+/* === Item ===
+   The wrapper around one trigger and its panel — React renders one per item,
+   and the vanilla controller marks one when the markup has it. Wrapped, each
+   trigger is the last button in its own wrapper, so the `:last-of-type` rule
+   above took every divider away: an accordion of closed items had no lines
+   between them at all. The divider belongs to the item instead. */
+.corn-accordion-item {
+  display: flex;
+  flex-direction: column;
+}
+
+.corn-accordion-item + .corn-accordion-item {
+  border-top: 1px solid var(--corn-border-light);
+}
+
+/* An open item's trigger is set off from its own panel. */
+.corn-accordion-item > .corn-accordion-trigger[data-open] {
+  border-bottom: 1px solid var(--corn-border-light);
+}
+
+/* === Panel (content area) === */
+.corn-accordion-panel {
+  padding: var(--corn-spacing-md) var(--corn-spacing-lg);
+  border-bottom: 1px solid var(--corn-border-light);
+  background: var(--corn-bg-primary);
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-base);
+  color: var(--corn-text-primary);
+  line-height: var(--corn-line-height);
+}
+
+.corn-accordion-panel:last-child {
+  border-bottom: none;
+}
+
+/* === Dark Mode === */
+[data-theme="dark"] .corn-accordion {
+  border-color: var(--corn-border-light);
+}
+
+[data-theme="dark"] .corn-accordion-trigger,
+[data-theme="dark"] .corn-accordion-panel {
+  background: var(--corn-bg-primary);
+}
+
+[data-theme="dark"] .corn-accordion-trigger:hover {
+  background: var(--corn-bg-secondary);
+}

package/dist/components/accordion/accordion.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Creates and manages an accordion component.
+ *
+ * @param {HTMLElement} containerEl - The wrapper element containing accordion items.
+ *   Each item must have:
+ *   - A trigger: `[data-accordion-trigger]` with a matching `data-accordion-item` value
+ *   - A panel:   `[data-accordion-panel]` with a matching `data-accordion-item` value
+ *   A nested accordion must carry `class="corn-accordion"` on its own wrapper.
+ *   That is how each one tells its items from a nested one's — CSS-first markup
+ *   already has it, since the styles do not work without it.
+ *
+ * @param {Object} options
+ * @param {boolean} [options.multiple=false] - Allow multiple panels open at once
+ * @param {string|string[]} [options.defaultOpen] - Item key(s) open on init
+ * @param {(panel: HTMLElement, key: string) => void} [options.onExpand] Called
+ *   the **first** time each panel opens, with the panel element, before
+ *   `onChange`. Ship a collapsed section with an empty panel and fill it here.
+ *
+ *   This is what makes a large document survivable: a 283-path OpenAPI
+ *   reference built 112,308 elements and 16MB of markup when every closed panel
+ *   was constructed up front, and froze the window. Once per key, not once per
+ *   open — reopening a branch must not rebuild it.
+ *
+ *   Same contract as `createNavigation`'s `onExpand(item)` and
+ *   `createTreeState`'s, so one "render these children" function serves
+ *   navigation, tree and content alike.
+ * @param {Function} [options.onChange] - Called with (key, isOpen) on toggle,
+ *   after `onExpand`, so a listener sees a panel that is already filled.
+ * @returns {{ open: Function, close: Function, toggle: Function, destroy: Function }}
+ */
+export function createAccordion(containerEl: HTMLElement, options?: {
+    multiple?: boolean;
+    defaultOpen?: string | string[];
+    onExpand?: (panel: HTMLElement, key: string) => void;
+    onChange?: Function;
+}): {
+    open: Function;
+    close: Function;
+    toggle: Function;
+    destroy: Function;
+};

package/dist/components/drawer/drawer.css

@@ -0,0 +1,117 @@
+/* === Drawer Backdrop === */
+.corn-drawer-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  background-color: transparent;
+  transition: background-color var(--corn-transition-base);
+}
+
+.corn-drawer-backdrop[data-visible] {
+  background-color: var(--corn-backdrop);
+}
+
+/* === Drawer Panel === */
+.corn-drawer {
+  position: fixed;
+  top: 0;
+  bottom: 0;
+  z-index: 1001;
+  /* md's geometry, so the default size is the default — see
+     scripts/size-fallback.test.js. `sm` and `lg` still win on specificity. */
+  width: 400px;
+  background: var(--corn-bg-primary);
+  box-shadow: var(--corn-shadow-lg);
+  display: flex;
+  flex-direction: column;
+  transition: transform var(--corn-transition-base);
+  overflow: hidden;
+}
+
+/* Sides */
+.corn-drawer[data-side='right'] {
+  right: 0;
+  transform: translateX(100%);
+}
+
+.corn-drawer[data-side='left'] {
+  left: 0;
+  transform: translateX(-100%);
+}
+
+.corn-drawer[data-side='right'].corn-drawer[data-open],
+.corn-drawer[data-side='left'].corn-drawer[data-open] {
+  transform: translateX(0);
+}
+
+/* Sizes */
+.corn-drawer[data-size='sm'] { width: 280px; }
+.corn-drawer[data-size='md'] { width: 400px; }
+.corn-drawer[data-size='lg'] { width: 560px; }
+
+/* === Header === */
+.corn-drawer-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--corn-spacing-md) var(--corn-spacing-lg);
+  border-bottom: 1px solid var(--corn-border-light);
+  flex-shrink: 0;
+}
+
+.corn-drawer-title {
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-lg);
+  font-weight: var(--corn-font-weight-bold);
+  color: var(--corn-text-primary);
+  margin: 0;
+  line-height: var(--corn-line-height);
+}
+
+.corn-drawer-close {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--corn-text-secondary);
+  font-size: var(--corn-font-size-lg);
+  line-height: 1;
+  padding: var(--corn-spacing-xs);
+  border-radius: var(--corn-radius-sm);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: color var(--corn-transition-fast), background-color var(--corn-transition-fast);
+  flex-shrink: 0;
+}
+
+.corn-drawer-close:hover {
+  color: var(--corn-text-primary);
+  background-color: var(--corn-bg-tertiary);
+}
+
+/* === Body === */
+.corn-drawer-body {
+  padding: var(--corn-spacing-lg);
+  overflow-y: auto;
+  flex: 1;
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-base);
+  color: var(--corn-text-primary);
+  line-height: var(--corn-line-height);
+}
+
+/* === Footer === */
+.corn-drawer-footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--corn-spacing-sm);
+  padding: var(--corn-spacing-md) var(--corn-spacing-lg);
+  border-top: 1px solid var(--corn-border-light);
+  flex-shrink: 0;
+}
+
+/* === Body scroll lock === */
+body.corn-drawer-open {
+  overflow: hidden;
+}

package/dist/components/drawer/drawer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates and manages a slide-in drawer panel.
+ *
+ * @param {Object} options
+ * @param {string} [options.title] - Drawer heading text
+ * @param {string|HTMLElement} [options.content] - Body content. A string is shown as text, never parsed as HTML; pass an element for markup.
+ * @param {HTMLElement} [options.footer] - Footer element
+ * @param {'left'|'right'} [options.side='right'] - Which side the drawer slides from
+ * @param {'sm'|'md'|'lg'} [options.size='md'] - Drawer width
+ * @param {boolean} [options.closeable=true] - Allow backdrop/esc/close-button to dismiss
+ * @param {Function} [options.onOpen] - Called when drawer opens
+ * @param {Function} [options.onClose] - Called when drawer closes
+ * @returns {{ open: Function, close: Function, destroy: Function, el: HTMLElement }}
+ */
+export function createDrawer(options?: {
+    title?: string;
+    content?: string | HTMLElement;
+    footer?: HTMLElement;
+    side?: "left" | "right";
+    size?: "sm" | "md" | "lg";
+    closeable?: boolean;
+    onOpen?: Function;
+    onClose?: Function;
+}): {
+    open: Function;
+    close: Function;
+    destroy: Function;
+    el: HTMLElement;
+};

package/dist/components/menu/menu.css

@@ -0,0 +1,106 @@
+.corn-menu {
+  position: fixed;
+  z-index: 8000;
+  min-width: 180px;
+  max-width: 320px;
+  padding: var(--corn-spacing-xs);
+  background-color: var(--corn-bg-primary);
+  border: 1px solid var(--corn-border-light);
+  border-radius: var(--corn-radius-md);
+  box-shadow: var(--corn-shadow-lg);
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-base);
+  color: var(--corn-text-primary);
+  opacity: 0;
+  transform: scale(0.97);
+  transform-origin: top left;
+  transition: opacity var(--corn-transition-fast), transform var(--corn-transition-fast);
+  pointer-events: none;
+}
+
+.corn-menu[data-placement='top'] { transform-origin: bottom left; }
+
+/* Closed is out of the accessibility tree, not just transparent: the vanilla
+   menu stays in the document between openings, and at opacity 0 a screen
+   reader's virtual cursor still reached its items — and could activate them.
+   Same pattern as .corn-popover, so the fade still plays: visibility holds
+   for the whole transition and flips at the end. */
+.corn-menu:not([data-visible]) {
+  visibility: hidden;
+  transition:
+    opacity var(--corn-transition-fast),
+    transform var(--corn-transition-fast),
+    visibility var(--corn-transition-fast);
+}
+
+.corn-menu[data-visible] {
+  opacity: 1;
+  transform: scale(1);
+  pointer-events: auto;
+}
+
+/* ── Items ──────────────────────────────────────────────────────────────────── */
+
+.corn-menu-item {
+  display: flex;
+  align-items: center;
+  gap: var(--corn-spacing-sm);
+  width: 100%;
+  padding: var(--corn-spacing-sm) var(--corn-spacing-md);
+  background: none;
+  border: none;
+  border-radius: var(--corn-radius-sm);
+  font: inherit;
+  color: var(--corn-text-primary);
+  text-align: left;
+  cursor: pointer;
+  transition: background-color var(--corn-transition-fast);
+}
+
+.corn-menu-item:hover:not(:disabled),
+.corn-menu-item:focus-visible {
+  outline: none;
+  background-color: var(--corn-bg-tertiary);
+}
+
+.corn-menu-item:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* A destructive item. The label says what it does; the colour backs it up. */
+.corn-menu-item[data-danger] {
+  color: var(--corn-danger);
+}
+
+.corn-menu-item[data-danger]:hover:not(:disabled),
+.corn-menu-item[data-danger]:focus-visible {
+  background-color: var(--corn-danger-light);
+}
+
+/* ── Groups ─────────────────────────────────────────────────────────────────── */
+
+/* A group after other entries is set off by a little space, so its heading
+   reads as starting something rather than belonging to the item above it. */
+.corn-menu-group:not(:first-child) {
+  margin-top: var(--corn-spacing-xs);
+}
+
+/* A heading, not an item: no role of its own, so the arrow keys pass over it,
+   and the group it names is announced by it. */
+.corn-menu-label {
+  padding: var(--corn-spacing-xs) var(--corn-spacing-md);
+  font-size: var(--corn-font-size-xs);
+  font-weight: var(--corn-font-weight-medium);
+  color: var(--corn-text-secondary);
+  cursor: default;
+  user-select: none;
+}
+
+/* ── Separator ──────────────────────────────────────────────────────────────── */
+
+.corn-menu-separator {
+  height: 1px;
+  margin: var(--corn-spacing-xs) 0;
+  background-color: var(--corn-border-light);
+}

package/dist/components/menu/menu.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Creates a dropdown menu anchored to a trigger element, with full keyboard
+ * navigation (arrows, Home/End, Escape) and `aria-haspopup`/menu roles.
+ *
+ * @param {HTMLElement} triggerEl
+ * @param {MenuOptions} options
+ * @returns {{ open: Function, close: Function, toggle: Function, destroy: Function }}
+ */
+export function createMenu(triggerEl: HTMLElement, options?: MenuOptions): {
+    open: Function;
+    close: Function;
+    toggle: Function;
+    destroy: Function;
+};
+export type MenuItemSpec = {
+    /**
+     * Visible text (ignored when `separator` is true).
+     */
+    label: string;
+    /**
+     * Value passed to `onSelect`.
+     */
+    value?: any;
+    /**
+     * Render the item non-interactive.
+     */
+    disabled?: boolean;
+    /**
+     * Render a divider instead of an item.
+     */
+    separator?: boolean;
+    /**
+     * A destructive action — "Delete", "Revoke".
+     * Coloured as danger; the label is what says so, so keep it a verb that does.
+     */
+    danger?: boolean;
+    /**
+     * Per-item select handler.
+     */
+    onSelect?: (value: any, item: MenuItemSpec) => void;
+};
+export type MenuGroupSpec = {
+    /**
+     * The heading. Not an item — the arrow keys pass over it —
+     * and it names the group for a screen reader.
+     */
+    group: string;
+    /**
+     * The entries under it.
+     */
+    items: MenuItemSpec[];
+};
+export type MenuOptions = {
+    /**
+     * Menu entries. An entry with
+     * `group` and `items` is a labelled group — the same shape as `options` elsewhere.
+     */
+    items: Array<MenuItemSpec | MenuGroupSpec>;
+    /**
+     * Preferred placement (flips if no room).
+     */
+    placement?: "bottom" | "top";
+    /**
+     * Close the menu after selecting an item.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Called when any item is selected.
+     */
+    onSelect?: (value: any, item: MenuItemSpec) => void;
+};

package/dist/components/modal/modal.css

@@ -0,0 +1,122 @@
+/* === Modal Backdrop === */
+.corn-modal-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  background-color: transparent;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--corn-spacing-md);
+  transition: background-color var(--corn-transition-base);
+}
+
+.corn-modal-backdrop[data-visible] {
+  background-color: var(--corn-backdrop);
+}
+
+/* === Modal Dialog === */
+.corn-modal {
+  background: var(--corn-bg-primary);
+  border-radius: var(--corn-radius-md);
+  box-shadow: var(--corn-shadow-lg);
+  display: flex;
+  flex-direction: column;
+  max-height: calc(100vh - var(--corn-spacing-xl) * 2);
+  width: 100%;
+  opacity: 0;
+  transform: translateY(-8px) scale(0.98);
+  transition:
+    opacity var(--corn-transition-base),
+    transform var(--corn-transition-base);
+}
+
+.corn-modal[data-visible] {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+/* Sizes */
+.corn-modal[data-size='sm']  { max-width: 400px; }
+.corn-modal[data-size='md']  { max-width: 560px; }
+.corn-modal[data-size='lg']  { max-width: 720px; }
+.corn-modal[data-size='xl']  { max-width: 960px; }
+.corn-modal[data-size='fullscreen'] {
+  max-width: 100%;
+  max-height: 100%;
+  height: 100%;
+  border-radius: 0;
+}
+
+/* === Header === */
+.corn-modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--corn-spacing-md) var(--corn-spacing-lg);
+  border-bottom: 1px solid var(--corn-border-light);
+  flex-shrink: 0;
+}
+
+.corn-modal-title {
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-lg);
+  font-weight: var(--corn-font-weight-bold);
+  color: var(--corn-text-primary);
+  margin: 0;
+  line-height: var(--corn-line-height);
+}
+
+.corn-modal-close {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--corn-text-secondary);
+  font-size: var(--corn-font-size-lg);
+  line-height: 1;
+  padding: var(--corn-spacing-xs);
+  border-radius: var(--corn-radius-sm);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: color var(--corn-transition-fast), background-color var(--corn-transition-fast);
+  flex-shrink: 0;
+}
+
+.corn-modal-close:hover {
+  color: var(--corn-text-primary);
+  background-color: var(--corn-bg-tertiary);
+}
+
+/* === Body === */
+.corn-modal-body {
+  padding: var(--corn-spacing-lg);
+  overflow-y: auto;
+  flex: 1;
+  font-family: var(--corn-font-family);
+  font-size: var(--corn-font-size-base);
+  color: var(--corn-text-primary);
+  line-height: var(--corn-line-height);
+}
+
+/* === Footer === */
+.corn-modal-footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--corn-spacing-sm);
+  padding: var(--corn-spacing-md) var(--corn-spacing-lg);
+  border-top: 1px solid var(--corn-border-light);
+  flex-shrink: 0;
+}
+
+/* === Body scroll lock === */
+body.corn-modal-open {
+  overflow: hidden;
+}
+
+/* === Dark Mode === */
+[data-theme="dark"] .corn-modal {
+  background: var(--corn-bg-primary);
+  border: 1px solid var(--corn-border-light);
+}

package/dist/components/modal/modal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Creates and manages a modal dialog.
+ *
+ * @param {Object} options
+ * @param {string} [options.title] - Modal heading text
+ * @param {string|HTMLElement} [options.content] - Body content. A string is shown as text, never parsed as HTML; pass an element for markup.
+ * @param {HTMLElement} [options.footer] - Footer element (e.g. buttons)
+ * @param {'sm'|'md'|'lg'|'xl'|'fullscreen'} [options.size='md'] - Dialog width
+ * @param {boolean} [options.closeable=true] - Show close button and allow backdrop/esc close
+ * @param {Function} [options.onOpen] - Called when modal opens
+ * @param {Function} [options.onClose] - Called when modal closes
+ * @returns {{ open: Function, close: Function, destroy: Function, el: HTMLElement }}
+ */
+export function createModal(options?: {
+    title?: string;
+    content?: string | HTMLElement;
+    footer?: HTMLElement;
+    size?: "sm" | "md" | "lg" | "xl" | "fullscreen";
+    closeable?: boolean;
+    onOpen?: Function;
+    onClose?: Function;
+}): {
+    open: Function;
+    close: Function;
+    destroy: Function;
+    el: HTMLElement;
+};