@plures/design-dojo 0.5.3 → 0.7.1

package/dist/overlays/Tooltip.svelte

@@ -0,0 +1,114 @@
+<!--
+  Tooltip — Brief label shown on hover/focus of the trigger.
+
+  GUI mode: floating overlay with fade transition, arrow pointer.
+  TUI mode: inline label rendered in terminal-safe monospace.
+
+  Usage: the `children` snippet receives `{ describedBy: string }` —
+  apply `aria-describedby={describedBy}` to the interactive element
+  inside so screen readers can associate the tooltip text with it.
+-->
+<script lang="ts">
+  import { useTui } from "../useTui.js";
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    /** Tooltip label text. */
+    content: string;
+    /** Position relative to the trigger. Default: "top". */
+    position?: "top" | "bottom" | "left" | "right";
+    /** Enable TUI mode. */
+    tui?: boolean;
+    /** The element that triggers the tooltip. Receives { describedBy } so you can
+     *  apply aria-describedby to the interactive element inside. */
+    children: Snippet<[{ describedBy: string }]>;
+  }
+
+  let { content, position = "top", tui = false, children }: Props = $props();
+
+  const getTuiCtx = useTui();
+  const isTui = $derived(tui || getTuiCtx());
+
+  let visible = $state(false);
+
+  function createId(prefix: string) {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return `${prefix}-${crypto.randomUUID()}`;
+    }
+    if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+      const array = new Uint32Array(1);
+      crypto.getRandomValues(array);
+      return `${prefix}-${array[0].toString(36)}`;
+    }
+    return `${prefix}-${Date.now().toString(36)}`;
+  }
+
+  const id = createId("tooltip");
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<span
+  class="tooltip-host"
+  class:tui={isTui}
+  onmouseenter={() => (visible = true)}
+  onmouseleave={() => (visible = false)}
+  onfocusin={() => (visible = true)}
+  onfocusout={() => (visible = false)}
+>
+  {@render children({ describedBy: id })}
+
+  {#if isTui}
+    {#if visible}
+      <span class="tui-tooltip" role="tooltip" {id}>[{content}]</span>
+    {/if}
+  {:else}
+    <span
+      class="tooltip tooltip--{position}"
+      class:tooltip--visible={visible}
+      role="tooltip"
+      {id}
+    >
+      {content}
+    </span>
+  {/if}
+</span>
+
+<style>
+  .tooltip-host {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  /* ===== GUI mode ===== */
+  .tooltip {
+    position: absolute;
+    z-index: var(--z-tooltip, 900);
+    padding: var(--space-1, 4px) var(--space-2, 8px);
+    background: var(--surface-2, #1e1e1e);
+    color: var(--color-text, #e8e8e8);
+    border: 1px solid var(--color-border, #2a2a2a);
+    border-radius: var(--radius-sm, 6px);
+    font-size: var(--text-xs, 12px);
+    white-space: nowrap;
+    pointer-events: none;
+    box-shadow: var(--elevation-2, var(--shadow-md));
+    opacity: 0;
+    transition: opacity 0.15s ease;
+  }
+
+  .tooltip--visible { opacity: 1; }
+
+  .tooltip--top    { bottom: calc(100% + var(--space-1, 4px)); left: 50%; transform: translateX(-50%); }
+  .tooltip--bottom { top:    calc(100% + var(--space-1, 4px)); left: 50%; transform: translateX(-50%); }
+  .tooltip--left   { right:  calc(100% + var(--space-1, 4px)); top: 50%;  transform: translateY(-50%); }
+  .tooltip--right  { left:   calc(100% + var(--space-1, 4px)); top: 50%;  transform: translateY(-50%); }
+
+  /* ===== TUI mode ===== */
+  .tui-tooltip {
+    margin-left: var(--space-1, 4px);
+    color: var(--tui-text-dim, #888888);
+    font-family: var(--font-mono, monospace);
+    font-size: var(--text-xs, 12px);
+  }
+</style>

package/dist/overlays/Tooltip.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { Snippet } from "svelte";
+interface Props {
+    /** Tooltip label text. */
+    content: string;
+    /** Position relative to the trigger. Default: "top". */
+    position?: "top" | "bottom" | "left" | "right";
+    /** Enable TUI mode. */
+    tui?: boolean;
+    /** The element that triggers the tooltip. Receives { describedBy } so you can
+     *  apply aria-describedby to the interactive element inside. */
+    children: Snippet<[{
+        describedBy: string;
+    }]>;
+}
+declare const Tooltip: import("svelte").Component<Props, {}, "">;
+type Tooltip = ReturnType<typeof Tooltip>;
+export default Tooltip;

package/dist/overlays/index.d.ts

@@ -0,0 +1,7 @@
+export { default as Tooltip } from "./Tooltip.svelte";
+export { default as Popover } from "./Popover.svelte";
+export { default as Dialog } from "./Dialog.svelte";
+export { default as Toast } from "./Toast.svelte";
+export { default as Menu } from "./Menu.svelte";
+export { default as ContextMenu } from "./ContextMenu.svelte";
+export type { MenuItem } from "./Menu.types.js";

package/dist/overlays/index.js

@@ -0,0 +1,6 @@
+export { default as Tooltip } from "./Tooltip.svelte";
+export { default as Popover } from "./Popover.svelte";
+export { default as Dialog } from "./Dialog.svelte";
+export { default as Toast } from "./Toast.svelte";
+export { default as Menu } from "./Menu.svelte";
+export { default as ContextMenu } from "./ContextMenu.svelte";

package/dist/primitives/Button.svelte

@@ -0,0 +1,217 @@
+<!--
+  Button — The first test. Does clicking it feel like pressing a real thing?
+
+  Features:
+  - Spring-physics press animation (scale + shadow depth)
+  - Focus ring with gentle spring
+  - Ripple effect on click (optional)
+  - Keyboard accessible (Enter + Space)
+  - Reduced motion support
+  - Variants: solid, ghost, outline
+  - Sizes: sm, md, lg
+  - TUI mode: box-drawing borders, terminal-safe colors, no decorative CSS
+-->
+<script lang="ts">
+  import { createSpring, SPRING_PRESETS } from "../motion/spring.js";
+  import { useTui } from "../useTui.js";
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    variant?: "solid" | "ghost" | "outline";
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    /** Enable TUI mode: box-drawing borders, terminal-safe colors, no decorative CSS. */
+    tui?: boolean;
+    onclick?: (e: MouseEvent) => void;
+    children: Snippet;
+  }
+
+  let { variant = "solid", size = "md", disabled = false, tui = false, onclick, children }: Props = $props();
+
+  const getTuiCtx = useTui();
+  const isTui = $derived(tui || getTuiCtx());
+
+  let buttonEl: HTMLButtonElement | undefined = $state();
+  let scale = $state(1);
+  let shadowDepth = $state(1);
+  let focusRing = $state(0);
+
+  // Spring controllers
+  let scaleSpring: ReturnType<typeof createSpring>;
+  let shadowSpring: ReturnType<typeof createSpring>;
+  let focusSpring: ReturnType<typeof createSpring>;
+
+  // Check for reduced motion preference
+  const prefersReducedMotion =
+    typeof window !== "undefined"
+      ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
+      : false;
+
+  $effect(() => {
+    if (prefersReducedMotion) return;
+
+    scaleSpring = createSpring(1, "snappy", (v) => (scale = v));
+    shadowSpring = createSpring(1, "snappy", (v) => (shadowDepth = v));
+    focusSpring = createSpring(0, "gentle", (v) => (focusRing = v));
+
+    return () => {
+      scaleSpring?.stop();
+      shadowSpring?.stop();
+      focusSpring?.stop();
+    };
+  });
+
+  function handlePointerDown() {
+    if (disabled || prefersReducedMotion) return;
+    scaleSpring?.set(0.96);
+    shadowSpring?.set(0.3);
+  }
+
+  function handlePointerUp() {
+    if (disabled || prefersReducedMotion) return;
+    scaleSpring?.set(1);
+    shadowSpring?.set(1);
+  }
+
+  function handlePointerLeave() {
+    if (disabled || prefersReducedMotion) return;
+    scaleSpring?.set(1);
+    shadowSpring?.set(1);
+  }
+
+  function handleFocus() {
+    if (prefersReducedMotion) { focusRing = 1; return; }
+    focusSpring?.set(1);
+  }
+
+  function handleBlur() {
+    if (prefersReducedMotion) { focusRing = 0; return; }
+    focusSpring?.set(0);
+  }
+</script>
+
+<button
+  bind:this={buttonEl}
+  class="btn btn-{variant} btn-{size}"
+  class:disabled
+  class:tui={isTui}
+  {disabled}
+  {onclick}
+  onpointerdown={handlePointerDown}
+  onpointerup={handlePointerUp}
+  onpointerleave={handlePointerLeave}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+  style:transform={isTui ? undefined : `scale(${scale})`}
+  style:--shadow-depth={isTui ? undefined : shadowDepth}
+  style:--focus-opacity={focusRing}
+>
+  {#if isTui}
+    <span class="tui-border-l">╠</span>{@render children()}<span class="tui-border-r">╣</span>
+  {:else}
+    {@render children()}
+  {/if}
+</button>
+
+<style>
+  .btn {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2, 8px);
+    border: none;
+    cursor: pointer;
+    font-family: inherit;
+    font-weight: 600;
+    white-space: nowrap;
+    user-select: none;
+    -webkit-user-select: none;
+    outline: none;
+    will-change: transform;
+
+    /* Focus ring via box-shadow */
+    box-shadow:
+      0 calc(1px * var(--shadow-depth, 1)) calc(2px * var(--shadow-depth, 1)) rgba(0,0,0,0.05),
+      0 calc(4px * var(--shadow-depth, 1)) calc(8px * var(--shadow-depth, 1)) rgba(0,0,0,0.1),
+      0 0 0 calc(3px * var(--focus-opacity, 0)) var(--color-accent, #6366f1);
+  }
+
+  /* Sizes */
+  .btn-sm { padding: 6px 14px; font-size: 13px; border-radius: 6px; }
+  .btn-md { padding: 10px 20px; font-size: 15px; border-radius: 8px; }
+  .btn-lg { padding: 14px 28px; font-size: 17px; border-radius: 10px; }
+
+  /* Variants */
+  .btn-solid {
+    background: var(--color-accent, #6366f1);
+    color: white;
+  }
+  .btn-ghost {
+    background: transparent;
+    color: var(--color-text, #e8e8e8);
+  }
+  .btn-ghost:hover { background: var(--alpha-10, rgba(255,255,255,0.1)); }
+  .btn-outline {
+    background: transparent;
+    color: var(--color-accent, #6366f1);
+    border: 1.5px solid var(--color-accent, #6366f1);
+  }
+
+  /* Disabled */
+  .disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* ===== TUI mode ===== */
+  .btn.tui {
+    background: var(--tui-surface, #16213e);
+    color: var(--tui-text, #e0e0e0);
+    border: 1px solid var(--tui-border, #0f3460);
+    border-radius: var(--tui-radius, 0px);
+    box-shadow: var(--tui-shadow, none);
+    font-family: var(--font-mono, monospace);
+    transform: none !important;
+    padding: 0 var(--space-2, 8px);
+  }
+  .btn.tui:hover:not(.disabled) {
+    background: var(--tui-highlight, #533483);
+    border-color: var(--tui-accent, #00d4ff);
+    color: var(--tui-accent, #00d4ff);
+  }
+  .btn.tui:focus-visible {
+    outline: 1px solid var(--tui-accent, #00d4ff);
+    outline-offset: 1px;
+  }
+  .btn.tui.btn-solid {
+    background: var(--tui-accent, #00d4ff);
+    color: var(--tui-bg, #1a1a2e);
+    border-color: var(--tui-accent, #00d4ff);
+  }
+  .btn.tui.btn-solid:hover:not(.disabled) {
+    background: var(--tui-highlight, #533483);
+    color: var(--tui-accent, #00d4ff);
+  }
+  .btn.tui.btn-ghost {
+    background: transparent;
+    border-color: transparent;
+    color: var(--tui-text, #e0e0e0);
+  }
+  .btn.tui.btn-ghost:hover:not(.disabled) {
+    background: var(--tui-highlight, #533483);
+    border-color: transparent;
+  }
+  .btn.tui.btn-outline {
+    background: transparent;
+    border-color: var(--tui-border, #0f3460);
+    color: var(--tui-accent, #00d4ff);
+  }
+  .tui-border-l,
+  .tui-border-r {
+    color: var(--tui-border, #0f3460);
+    user-select: none;
+    font-style: normal;
+  }
+</style>

package/dist/primitives/Button.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+interface Props {
+    variant?: "solid" | "ghost" | "outline";
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    /** Enable TUI mode: box-drawing borders, terminal-safe colors, no decorative CSS. */
+    tui?: boolean;
+    onclick?: (e: MouseEvent) => void;
+    children: Snippet;
+}
+declare const Button: import("svelte").Component<Props, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/primitives/ContextMenu.svelte

@@ -0,0 +1,242 @@
+<!--
+  ContextMenu — Generic right-click / programmatic context menu primitive.
+
+  Features:
+  - Positioned via x/y screen coordinates; auto-flips near container edges
+  - Keyboard navigation: ArrowUp/Down, Enter to select, Escape to close
+  - Click-outside closes the menu
+  - Separator rows (visual dividers)
+  - Disabled items are rendered but skipped by keyboard navigation
+  - ARIA: role="menu" with role="menuitem" children
+-->
+<script lang="ts">
+  import type { ContextMenuItem, ContextMenuActionItem } from "./ContextMenu.types.js";
+
+  // Module-level counter ensures unique IDs even when multiple menus mount simultaneously
+  let _menuCounter = 0;
+
+  interface Props {
+    /** Menu items to display. */
+    items: ContextMenuItem[];
+    /** Screen X coordinate (pixels from left of nearest positioned ancestor). */
+    x: number;
+    /** Screen Y coordinate (pixels from top of nearest positioned ancestor). */
+    y: number;
+    /** Fired when the user activates a non-disabled, non-separator item. */
+    onselect?: (item: ContextMenuActionItem) => void;
+    /** Fired when the menu should close (Escape, outside click, item selected). */
+    onclose?: () => void;
+    /** Custom CSS class. */
+    class?: string;
+  }
+
+  let { items, x, y, onselect, onclose, class: className = "" }: Props = $props();
+
+  let menuEl: HTMLElement | undefined = $state();
+
+  // Stable per-instance prefix for item IDs (avoids collisions when multiple menus mount)
+  const menuId = `ctxmenu-${_menuCounter++}`;
+
+  // Flipped position — adjusted after mount to keep within container bounds
+  let adjustedX = $state(0);
+  let adjustedY = $state(0);
+
+  let activeIdx = $state(-1);
+
+  // Type guard: is the item an actionable (non-separator) item?
+  function isAction(item: ContextMenuItem): item is ContextMenuActionItem {
+    return !item.separator;
+  }
+
+  // Navigable items (skip separators + disabled)
+  const navigable = $derived(
+    items
+      .map((it, i) => ({ it, i }))
+      .filter((entry): entry is { it: ContextMenuActionItem; i: number } =>
+        isAction(entry.it) && !entry.it.disabled,
+      ),
+  );
+
+  // DOM id of the currently active menuitem (drives aria-activedescendant)
+  const activeItemId = $derived(
+    activeIdx >= 0 && activeIdx < navigable.length
+      ? `${menuId}-${navigable[activeIdx].it.id}`
+      : undefined,
+  );
+
+  // Precomputed map: item-list index → navigable index (O(1) lookup during render)
+  const navIndexByItemIndex = $derived(new Map(navigable.map((n, idx) => [n.i, idx])));
+
+  // Flip position when menu would overflow the containing positioned element
+  $effect(() => {
+    const px = x;
+    const py = y;
+    if (!menuEl) {
+      adjustedX = px;
+      adjustedY = py;
+      return;
+    }
+    const menuRect = menuEl.getBoundingClientRect();
+    const parentEl = menuEl.offsetParent as HTMLElement | null;
+    const parentRect = parentEl ? parentEl.getBoundingClientRect() : { width: window.innerWidth, height: window.innerHeight };
+    const parentW = parentRect.width;
+    const parentH = parentRect.height;
+    // Flip horizontally: try left of cursor first; clamp so menu always stays in bounds
+    adjustedX = px + menuRect.width > parentW
+      ? Math.max(0, Math.min(px - menuRect.width, parentW - menuRect.width))
+      : px;
+    // Flip vertically: try above cursor first; clamp so menu always stays in bounds
+    adjustedY = py + menuRect.height > parentH
+      ? Math.max(0, Math.min(py - menuRect.height, parentH - menuRect.height))
+      : py;
+  });
+
+  // Close on outside click
+  $effect(() => {
+    function handleOutside(e: MouseEvent) {
+      if (menuEl && !menuEl.contains(e.target as Node)) onclose?.();
+    }
+    document.addEventListener("mousedown", handleOutside);
+    return () => document.removeEventListener("mousedown", handleOutside);
+  });
+
+  // Auto-focus the menu on mount for keyboard nav
+  $effect(() => {
+    menuEl?.focus();
+  });
+
+  function activate(item: ContextMenuActionItem) {
+    if (item.disabled) return;
+    onselect?.(item);
+    onclose?.();
+  }
+
+  function onKeyDown(e: KeyboardEvent) {
+    const count = navigable.length;
+    if (e.key === "Escape") { e.preventDefault(); onclose?.(); return; }
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      if (count === 0) return;
+      activeIdx = activeIdx < count - 1 ? activeIdx + 1 : 0;
+      return;
+    }
+    if (e.key === "ArrowUp") {
+      e.preventDefault();
+      if (count === 0) return;
+      activeIdx = activeIdx > 0 ? activeIdx - 1 : count - 1;
+      return;
+    }
+    if (e.key === "Enter") {
+      if (count === 0 || activeIdx < 0 || activeIdx >= count) return;
+      e.preventDefault();
+      activate(navigable[activeIdx].it);
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<ul
+  bind:this={menuEl}
+  class="ctx-menu {className}"
+  style:left="{adjustedX}px"
+  style:top="{adjustedY}px"
+  role="menu"
+  tabindex="-1"
+  aria-activedescendant={activeItemId}
+  onkeydown={onKeyDown}
+  onmousedown={(e) => e.stopPropagation()}
+>
+  {#each items as item, i}
+    {#if item.separator}
+      <li class="ctx-menu__sep" role="separator" aria-hidden="true"></li>
+    {:else if isAction(item)}
+      {@const navIdx = navIndexByItemIndex.get(i) ?? -1}
+      <li
+        id="{menuId}-{item.id}"
+        class="ctx-menu__item"
+        class:ctx-menu__item--disabled={item.disabled}
+        class:ctx-menu__item--active={navIdx === activeIdx}
+        role="menuitem"
+        tabindex={item.disabled ? undefined : -1}
+        aria-disabled={item.disabled ? "true" : undefined}
+        onclick={() => activate(item)}
+        onkeydown={(e) => {
+          if (e.key === "Enter" || e.key === " ") { e.preventDefault(); activate(item); }
+        }}
+        onmouseenter={() => { if (!item.disabled) activeIdx = navIdx; }}
+      >
+        {#if item.icon}
+          <span class="ctx-menu__icon" aria-hidden="true">{item.icon}</span>
+        {/if}
+        <span class="ctx-menu__label">{item.label}</span>
+        {#if item.shortcut}
+          <span class="ctx-menu__shortcut" aria-hidden="true">{item.shortcut}</span>
+        {/if}
+      </li>
+    {/if}
+  {/each}
+</ul>
+
+<style>
+  .ctx-menu {
+    position: absolute;
+    background: var(--surface-2, #1e1e1e);
+    border: 1px solid var(--color-border, #2a2a2a);
+    border-radius: var(--radius-md, 10px);
+    padding: var(--space-1, 4px);
+    min-width: 160px;
+    z-index: 200;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+    list-style: none;
+    margin: 0;
+    outline: none;
+    user-select: none;
+  }
+
+  .ctx-menu__sep {
+    height: 1px;
+    background: var(--color-border, #2a2a2a);
+    margin: var(--space-1, 4px) var(--space-2, 8px);
+  }
+
+  .ctx-menu__item {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2, 8px);
+    padding: 5px var(--space-2, 8px);
+    border-radius: var(--radius-sm, 6px);
+    color: var(--color-text, #e8e8e8);
+    font-size: 13px;
+    cursor: pointer;
+    outline: none;
+    transition: background 0.1s;
+  }
+
+  .ctx-menu__item:hover:not(.ctx-menu__item--disabled),
+  .ctx-menu__item--active:not(.ctx-menu__item--disabled) {
+    background: var(--alpha-10, rgba(255, 255, 255, 0.1));
+  }
+
+  .ctx-menu__item--disabled {
+    color: var(--color-text-subtle, #555);
+    cursor: default;
+  }
+
+  .ctx-menu__icon {
+    font-size: 14px;
+    width: 16px;
+    text-align: center;
+    flex-shrink: 0;
+  }
+
+  .ctx-menu__label {
+    flex: 1;
+  }
+
+  .ctx-menu__shortcut {
+    font-size: 11px;
+    color: var(--color-text-subtle, #555);
+    font-family: var(--font-mono, monospace);
+    flex-shrink: 0;
+  }
+</style>

package/dist/primitives/ContextMenu.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { ContextMenuItem, ContextMenuActionItem } from "./ContextMenu.types.js";
+interface Props {
+    /** Menu items to display. */
+    items: ContextMenuItem[];
+    /** Screen X coordinate (pixels from left of nearest positioned ancestor). */
+    x: number;
+    /** Screen Y coordinate (pixels from top of nearest positioned ancestor). */
+    y: number;
+    /** Fired when the user activates a non-disabled, non-separator item. */
+    onselect?: (item: ContextMenuActionItem) => void;
+    /** Fired when the menu should close (Escape, outside click, item selected). */
+    onclose?: () => void;
+    /** Custom CSS class. */
+    class?: string;
+}
+declare const ContextMenu: import("svelte").Component<Props, {}, "">;
+type ContextMenu = ReturnType<typeof ContextMenu>;
+export default ContextMenu;

package/dist/primitives/ContextMenu.types.js

@@ -0,0 +1 @@
+export {};