Kobiowu

Problem Statement

Overlays (modals, toasts, drawers, confirm dialogs, bottom sheets) are needed everywhere but painful everywhere: each UI framework reinvents them, they're hard to launch imperatively (e.g. await confirm() from inside a function, not by rendering JSX), they fight over z-index, they need portal/focus/escape/scroll-lock handling, and most libraries force their own styling on you. There's no small, framework-neutral primitive that just does the orchestration and leaves the look to you.

Proposed Solution

Kobiowu is a framework-agnostic, headless overlay orchestration engine. One imperative API — kobiowu.launchModal/launchToast/launchDrawer/launchAlert/launchSheet(content, options) — mounts arbitrary content (an HTML string or a framework component) into a managed overlay layer and returns an OverlayRef you can open()/close() programmatically. It ships zero styling (you bring the look) and works in React, Vue, Svelte, or plain HTML.

Full Solution Details

• Overlay types — modal (centered/scrollable/size-constrained, escape-to-close), toast (positions, duration/persist, pause-on-hover, progress bar, per-position limit, swipe-to-dismiss, types: success/error/warning/info/loading), drawer (4 sides, snap points, push-content, overlay toggle), alert (confirm/prompt/info/destructive with onConfirm/onCancel), and bottom sheet (snap points).
• OverlayRef — every launch returns a handle: await ref.close(reason), ref.open(), etc., for full programmatic control.
• Global config — kobiowu.config({ portalTarget, ariaLive, animationPreset, animationDuration, zIndexBase, defaults }) sets app-wide defaults that any per-launch option overrides.
• Accessibility & layering — ariaLive for toasts, escape handling, and a structured zIndexBase map (modal/toast/alert/drawer) so layers never collide.
• Grouping — group tags for filtering/dismissing batches of overlays.

Technical Documentation

Written in TypeScript and published to npm. The core is a headless orchestrator: it owns a portal root (default document.body, configurable via portalTarget), an overlay registry, a z-index layering policy, animation presets (fade/scale/slide/none), and the lifecycle (mount → animate-in → user interaction → animate-out → unmount) — but renders no styles of its own. Because content can be a raw HTML string (alerts wire callbacks to [data-kb-confirm]/[data-kb-cancel] attributes), the engine is genuinely framework-neutral; framework adapters can pass components instead. Each overlay's OverlayRef exposes imperative open/close with a close reason, enabling await-style flows (e.g. resolve a confirm dialog's result).

Tech Stack

TypeScript (headless core), npm distribution; framework-agnostic (React/Vue/Svelte/vanilla); portal + z-index + focus/escape + animation orchestration.

System Design

 kobiowu.launch{Modal,Toast,Drawer,Alert,Sheet}(content, options)
        │ returns OverlayRef { open(), close(reason) }
        ▼
  Headless orchestrator
   ├── portal manager (portalTarget, default document.body)
   ├── overlay registry + group tags
   ├── z-index layering (zIndexBase: modal/toast/alert/drawer)
   ├── lifecycle: mount → animate(fade/scale/slide) → close → unmount
   ├── a11y: ariaLive, escape, focus
   └── per-type behavior (toast positions/swipe, drawer snap points, alert callbacks)
        │ ZERO styling — host app brings the look
        ▼
   Works with React · Vue · Svelte · plain HTML (content can be an HTML string)

Smart Architectural Decisions

• Headless + imperative is the core insight. Separating overlay orchestration (portals, layering, lifecycle, a11y) from appearance, and exposing it imperatively with an OverlayRef, solves the awkward "how do I await confirm() from a function" problem that JSX-only modal libs can't.
• Framework-agnostic via HTML strings + adapters. Accepting raw HTML (with data-kb-* hooks for callbacks) means the same engine works in any stack — a deliberate lowest-common-denominator design that maximizes reach.
• Centralized z-index policy. A configurable zIndexBase map per overlay type eliminates the classic z-index war between modals/toasts/drawers.
• Config defaults + per-launch overrides. Global kobiowu.config() with per-call overrides is a clean, predictable options-resolution model.
• Real-world overlay nuance — toast pause-on-hover/limit/swipe, drawer snap points, destructive-alert callbacks — shows the API was designed from actual UX needs, not a toy spec.

Impacts

A published, zero-styling overlay engine that any framework (or none) can adopt for modals/toasts/drawers/alerts/sheets with correct portaling, layering, accessibility, and imperative control — without inheriting someone else's design system.

Demonstrated Skills

Headless library/API design (separation of orchestration from presentation); framework-agnostic engineering (vanilla core + adapters, HTML-string content); imperative overlay/portal management; z-index layering and lifecycle/animation orchestration; accessibility (ariaLive, focus, escape); TypeScript and npm packaging.