@w5-ui/svelte 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@w5-ui/svelte",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Svelte 5 components for the Dash UI design system - mirrors the @w5-ui/react API 1:1. Part of Webber's design systems.",
   "keywords": [
     "svelte",
@@ -45,10 +45,10 @@
   },
   "dependencies": {
     "@w5-ui/assets": "^0.2.1",
-    "@w5-ui/tokens": "^0.2.1"
+    "@w5-ui/tokens": "^0.5.0"
   },
   "devDependencies": {
-    "svelte": "^5.55.8",
+    "svelte": "^5.55.9",
     "typescript": "^5.5.0"
   },
   "files": [

package/src/lib/actions/portal.ts

@@ -0,0 +1,55 @@
+import type { Action } from 'svelte/action'
+
+/**
+ * Move a DOM node into `target` (default: `document.body`) for the
+ * lifetime of the action. Used by floating UI primitives so
+ * `position: fixed` + `z-index` always escape:
+ *
+ *   - ancestor `overflow: hidden` / `overflow: clip` (would clip
+ *     a non-portalled child even at `position: fixed` if the
+ *     ancestor establishes a containing block)
+ *   - ancestor `transform`, `filter`, `perspective`, `contain: paint`,
+ *     `will-change: transform` (any of which create a containing
+ *     block for `position: fixed` descendants, defeating viewport
+ *     positioning)
+ *   - ancestor stacking contexts with a lower `z-index` than the
+ *     popover's `z-index`, which would otherwise trap it underneath
+ *     sibling chrome
+ *
+ * The node still belongs to the Svelte component that owns it: props,
+ * reactivity, lifecycle, and event handlers continue to work; only
+ * the DOM position changes. The action removes the node on destroy
+ * so cleanup is automatic.
+ *
+ * SSR-safe: actions don't run during server rendering.
+ */
+export const portal: Action<HTMLElement, HTMLElement | string | undefined> = (
+  node,
+  target = 'body',
+) => {
+  const resolveTarget = (value: HTMLElement | string | undefined): HTMLElement | null => {
+    if (value === undefined) return document.body
+    if (typeof value === 'string') {
+      return document.querySelector<HTMLElement>(value)
+    }
+    return value
+  }
+
+  const move = (value: HTMLElement | string | undefined) => {
+    const parent = resolveTarget(value)
+    if (parent !== null && parent !== node.parentNode) {
+      parent.appendChild(node)
+    }
+  }
+
+  move(target)
+
+  return {
+    update(next: HTMLElement | string | undefined) {
+      move(next)
+    },
+    destroy() {
+      node.remove()
+    },
+  }
+}

package/src/lib/components/ContextMenu.svelte

@@ -1,8 +1,23 @@
 <script lang="ts" module>
+  export type ContextMenuPillVariant = 'success' | 'warn' | 'danger' | 'info' | 'neutral';
+  /** Inline badge rendered where the label's `{pill}` placeholder sits. */
+  export interface ContextMenuPill {
+    text: string;
+    variant?: ContextMenuPillVariant;
+  }
   export interface ContextMenuItem {
     id: string;
+    /** Item copy. May contain a single `{pill}` placeholder slot which is
+     *  replaced by an inline {@link ContextMenuPill} when `pill` is set. */
     label: string;
+    /** Inline badge substituted for the `{pill}` slot in `label`. */
+    pill?: ContextMenuPill;
+    /** Red tone (destructive). Mutually exclusive with `warning`. */
     danger?: boolean;
+    /** Yellow tone (caution / heads-up). Mutually exclusive with `danger`. */
+    warning?: boolean;
+    /** Green tone (active / positive state). Mutually exclusive with `danger` + `warning`. */
+    success?: boolean;
     disabled?: boolean;
   }
   export type ContextMenuEntry = ContextMenuItem | { separator: true };
@@ -10,6 +25,22 @@
 
 <script lang="ts">
   import { onDestroy, tick } from 'svelte';
+  import Pill from './Pill.svelte';
+
+  const PILL_SLOT = '{pill}';
+
+  /** Split a label around its first `{pill}` slot so the pill can be
+   *  rendered inline between the surrounding copy. Returns null when the
+   *  item has no pill or no slot, signalling a plain-text label. */
+  function pillParts(entry: ContextMenuItem): { before: string; after: string } | null {
+    if (entry.pill === undefined) return null;
+    const idx = entry.label.indexOf(PILL_SLOT);
+    if (idx === -1) return null;
+    return {
+      before: entry.label.slice(0, idx),
+      after: entry.label.slice(idx + PILL_SLOT.length),
+    };
+  }
 
   interface Props {
     items?: ContextMenuEntry[];
@@ -110,10 +141,16 @@
           aria-disabled={entry.disabled || undefined}
           data-active={actionIndex(entry) === activeIdx ? 'true' : undefined}
           data-danger={entry.danger || undefined}
-          class="flex cursor-pointer items-center whitespace-nowrap rounded-[5px] px-3 py-1.5 text-13 text-text-2 outline-none hover:bg-row-active hover:text-text-1 data-[active=true]:bg-row-active data-[active=true]:text-text-1 data-[danger=true]:text-status-danger data-[danger=true]:hover:bg-status-danger/10 aria-disabled:cursor-not-allowed aria-disabled:opacity-40"
+          data-warning={entry.warning || undefined}
+          data-success={entry.success || undefined}
+          class="flex cursor-pointer items-center whitespace-nowrap rounded-[5px] px-3 py-1.5 text-13 text-text-2 outline-none hover:bg-row-active hover:text-text-1 data-[active=true]:bg-row-active data-[active=true]:text-text-1 data-[danger=true]:text-status-danger data-[danger=true]:hover:bg-status-danger/10 data-[warning=true]:text-status-warning data-[warning=true]:hover:bg-status-warning/10 data-[success=true]:text-status-success data-[success=true]:hover:bg-status-success/10 aria-disabled:cursor-not-allowed aria-disabled:opacity-40"
           onmouseenter={() => (activeIdx = actionIndex(entry))}
           onmousedown={(e) => { e.preventDefault(); (() => { if (!entry.disabled) activate(entry.id); })(); }}
-        >{entry.label}</li>
+        >{#if pillParts(entry)}{@const parts = pillParts(entry)}{parts?.before}<Pill
+            variant={entry.pill?.variant ?? 'neutral'}
+            showDot={false}
+            class="mx-0.5 !px-1.5 !py-0 text-[10px] font-semibold leading-[1]"
+          >{entry.pill?.text}</Pill>{parts?.after}{:else}{entry.label}{/if}</li>
       {/if}
     {/each}
   </ul>

package/src/lib/components/Modal.svelte

@@ -1,3 +1,7 @@
+<script module lang="ts">
+  export type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+</script>
+
 <script lang="ts">
   import { tick } from 'svelte';
   import IconButton from './IconButton.svelte';
@@ -5,6 +9,9 @@
   interface Props {
     open?: boolean;
     title: string;
+    /** Panel width. `md` (520px) is the default; larger sizes suit
+     *  data-dense or editor-style dialogs. Always capped at 90vw. */
+    size?: ModalSize;
     children?: import('svelte').Snippet;
     footer?: import('svelte').Snippet;
   }
@@ -12,9 +19,21 @@
   let {
     open = $bindable(false),
     title,
+    size = 'md',
     children,
     footer
   }: Props = $props();
+
+  // Pre-composed width utilities so Tailwind's static scanner keeps
+  // each class in the build. The React sibling expresses the same
+  // scale via `.modal--*` rules in dashboard.css.
+  const SIZE: Record<ModalSize, string> = {
+    sm: 'w-[400px]',
+    md: 'w-[520px]',
+    lg: 'w-[720px]',
+    xl: 'w-[960px]',
+    '2xl': 'w-[1200px]'
+  };
   const titleId = `modal-title-${Math.random().toString(36).slice(2, 9)}`;
   const FOCUSABLE =
     'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
@@ -90,7 +109,7 @@
 >
   <div
     bind:this={modalEl}
-    class="w-[520px] max-w-[90vw] overflow-hidden rounded-xl border border-border-2 bg-bg-1 shadow-modal"
+    class="{SIZE[size]} max-w-[90vw] overflow-hidden rounded-xl border border-border-2 bg-bg-1 shadow-modal"
     role="dialog"
     aria-modal="true"
     aria-labelledby={titleId}

package/src/lib/components/Popover.svelte

@@ -5,6 +5,8 @@
 <script lang="ts">
   import { onMount, onDestroy, tick } from 'svelte';
   import Button from './Button.svelte';
+  import { portal } from '../actions/portal.ts';
+  import { computePanelPosition } from './popover-position.ts';
 
   interface Props {
     label: string;
@@ -66,17 +68,28 @@
   function recomputePosition() {
     if (!triggerEl || !panelEl) return;
     const tr = triggerEl.getBoundingClientRect();
-    const margin = 8;
-    const offset = 6; // gap between trigger bottom and panel top
-    const panelWidth = panelEl.offsetWidth;
-    let left: number;
-    if (placement === 'bottom-start') left = tr.left;
-    else if (placement === 'bottom-end') left = tr.right - panelWidth;
-    else left = tr.left + tr.width / 2 - panelWidth / 2; // 'bottom'
-    // Clamp into the visible viewport with the configured gutter.
-    left = Math.max(margin, Math.min(left, window.innerWidth - panelWidth - margin));
+    // Delegate the actual math to a pure helper so the auto-flip
+    // rule (panel goes above the trigger when below would overflow
+    // AND above has more room) is unit-testable without mounting
+    // the component. See `popover-position.ts`.
+    const { top, left } = computePanelPosition({
+      triggerRect: {
+        top: tr.top,
+        bottom: tr.bottom,
+        left: tr.left,
+        right: tr.right,
+        width: tr.width,
+      },
+      panelWidth: panelEl.offsetWidth,
+      panelHeight: panelEl.offsetHeight,
+      viewportWidth: window.innerWidth,
+      viewportHeight: window.innerHeight,
+      placement,
+      margin: 8,
+      offset: 6,
+    });
+    panelTop = top;
     panelLeft = left;
-    panelTop = tr.bottom + offset;
   }
 
   async function toggle() {
@@ -111,7 +124,14 @@
   }
 
   function onPointer(e: PointerEvent) {
-    if (open && !rootEl?.contains(e.target as Node)) open = false;
+    if (!open) return;
+    const target = e.target as Node;
+    // The panel is portalled to <body> so it's no longer a descendant
+    // of rootEl. Check both so clicks INSIDE the panel don't count as
+    // outside-clicks and immediately close the popover.
+    if (rootEl?.contains(target)) return;
+    if (panelEl?.contains(target)) return;
+    open = false;
   }
 
   function onResize() {
@@ -141,7 +161,7 @@
   });
 </script>
 
-<div class="relative inline-block" bind:this={rootEl}>
+<div class="relative inline-flex items-center" bind:this={rootEl}>
   {#if trigger}
     {@render trigger({ toggle, open })}
   {:else}
@@ -158,6 +178,7 @@
     -->
     <div
       bind:this={panelEl}
+      use:portal
       role="dialog"
       aria-labelledby={title ? titleId : undefined}
       class="fixed z-[9100] min-w-[200px] max-w-[320px] rounded-[10px] border border-border-3 bg-bg-2 shadow-[0_8px_32px_rgba(0,0,0,0.5)] focus:outline-none"

package/src/lib/components/Topbar.svelte

@@ -1,11 +1,27 @@
 <script module lang="ts">
+  import type { AppLogoKey } from '@w5-ui/assets';
+
+  /** Logo identifier. Either a built-in `AppLogoKey` (resolved via
+   *  `@w5-ui/assets`'s `appLogos` map) or a raw URL string — use the
+   *  latter when the consuming app wants to brand an entry with its
+   *  own image without having to upstream a new asset into the
+   *  design system. */
+  export type AppLogo = AppLogoKey | (string & {})
   export interface AppDef { id: string; label: string; logo: AppLogo }
   export type TopbarStatus = 'ok' | 'warn' | 'danger' | 'neutral';
 </script>
 
 <script lang="ts">
   import type { Snippet } from 'svelte';
-  import { appLogos, type AppLogoKey as AppLogo } from '@w5-ui/assets';
+  import { appLogos, type AppLogoKey } from '@w5-ui/assets';
+
+  /** Resolve an `AppLogo` to an `<img src>` URL. Known keys go
+   *  through the bundled `appLogos` map; anything else is treated as
+   *  a URL the consumer supplied directly. */
+  function resolveLogo(logo: string): string {
+    if (logo in appLogos) return appLogos[logo as AppLogoKey]
+    return logo
+  }
   import IconButton from './IconButton.svelte';
   import Avatar from './Avatar.svelte';
   import CaretIcon from '../icons/CaretIcon.svelte';
@@ -28,6 +44,12 @@
     notificationCount?: number;
     /** Health colour of the site-name status ring. Defaults to 'ok' (green). */
     status?: TopbarStatus;
+    /** Optional URL of a square logo (or w5-ui `AppLogoKey`) to render in
+     *  place of the status dot, next to `siteName`. The status colour
+     *  becomes a thin ring AROUND the logo so the health signal is
+     *  preserved without claiming a dedicated dot. Falls back to the
+     *  classic status-dot layout when undefined. */
+    siteLogo?: AppLogo;
     /** When false, the site label renders as a static element instead of a
      * site-switcher dropdown trigger. Use for single-site dashboards. */
     siteSwitchable?: boolean;
@@ -45,6 +67,7 @@
     initials = 'MS',
     notificationCount = 1,
     status = 'ok',
+    siteLogo,
     siteSwitchable = true,
     actions,
     onappchange,
@@ -67,11 +90,45 @@
     danger: 'bg-status-danger',
     neutral: 'bg-status-neutral',
   };
+  /** Solid-colour ring drawn AROUND the site logo (when `siteLogo` is
+   *  set) so the health signal stays visible without the dot+halo
+   *  treatment. Pre-composed for the Tailwind static scanner. */
+  const LOGO_RING: Record<TopbarStatus, string> = {
+    ok: 'ring-status-success',
+    warn: 'ring-status-warning',
+    danger: 'ring-status-danger',
+    neutral: 'ring-status-neutral',
+  };
 
   let ringWrapClass = $derived(
     `inline-flex h-[18px] w-[18px] items-center justify-center rounded-full ${RING_BG[status]}`,
   );
   let ringDotClass = $derived(`h-2 w-2 rounded-full ${RING_DOT[status]}`);
+  let logoRingClass = $derived(
+    `inline-flex h-6 w-6 items-center justify-center overflow-hidden rounded-full ring-2 ring-inset ${LOGO_RING[status]}`,
+  );
+
+  // Status-coloured glow drawn behind the site logo. Replaces the old
+  // "N down" headline pill as the at-a-glance health signal: green when
+  // healthy, amber when degraded, red when something is down. Rendered
+  // as a blurred radial puddle behind the logo so the colour bleeds
+  // softly past the rim rather than reading as a hard second ring.
+  // Neutral (no data yet) gets no glow so a cold-start chrome stays calm.
+  const GLOW_TOKEN: Record<TopbarStatus, string | null> = {
+    ok: '--status-success',
+    warn: '--status-warning',
+    danger: '--status-danger',
+    neutral: null,
+  };
+  let logoGlowStyle = $derived.by(() => {
+    const token = GLOW_TOKEN[status];
+    if (token === null) return 'opacity: 0;';
+    const colour = `var(${token})`;
+    return (
+      `background: radial-gradient(closest-side, ${colour}, transparent);` +
+      ' opacity: 0.85; filter: blur(5px);'
+    );
+  });
 </script>
 
 <!--
@@ -90,14 +147,47 @@
       class="flex cursor-pointer items-center gap-2 rounded-md px-2.5 py-1.5 hover:bg-row-hover focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand-05"
       aria-label="Switch site: {siteName}"
       aria-haspopup="menu"
+      title={`${siteName} — status: ${status}`}
     >
-      <span class={ringWrapClass}><span class={ringDotClass}></span></span>
+      {#if siteLogo !== undefined}
+        <span class="relative inline-flex h-6 w-6 items-center justify-center">
+          <span
+            data-testid="site-logo-glow"
+            aria-hidden="true"
+            class="pointer-events-none absolute -inset-1.5 rounded-full transition-opacity duration-300"
+            style={logoGlowStyle}
+          ></span>
+          <span class={`relative ${logoRingClass}`} aria-hidden="true">
+            <img src={resolveLogo(siteLogo)} alt="" width="24" height="24" class="h-full w-full object-cover" />
+          </span>
+        </span>
+      {:else}
+        <span class={ringWrapClass}><span class={ringDotClass}></span></span>
+      {/if}
       <span class="text-13 font-medium text-text-1" aria-hidden="true">{siteName}</span>
       <CaretIcon class="h-3.5 w-3.5 text-text-3" />
     </button>
   {:else}
-    <div class="flex items-center gap-2 px-2.5 py-1.5" role="presentation">
-      <span class={ringWrapClass}><span class={ringDotClass}></span></span>
+    <div
+      class="flex items-center gap-2 px-2.5 py-1.5"
+      role="presentation"
+      title={`${siteName} — status: ${status}`}
+    >
+      {#if siteLogo !== undefined}
+        <span class="relative inline-flex h-6 w-6 items-center justify-center">
+          <span
+            data-testid="site-logo-glow"
+            aria-hidden="true"
+            class="pointer-events-none absolute -inset-1.5 rounded-full transition-opacity duration-300"
+            style={logoGlowStyle}
+          ></span>
+          <span class={`relative ${logoRingClass}`} aria-hidden="true">
+            <img src={resolveLogo(siteLogo)} alt="" width="24" height="24" class="h-full w-full object-cover" />
+          </span>
+        </span>
+      {:else}
+        <span class={ringWrapClass}><span class={ringDotClass}></span></span>
+      {/if}
       <span class="text-13 font-medium text-text-1">{siteName}</span>
     </div>
   {/if}
@@ -114,7 +204,7 @@
         onclick={() => { activeApp = a.id; onappchange?.(a.id); }}
       >
         <img
-          src={appLogos[a.logo]}
+          src={resolveLogo(a.logo)}
           alt=""
           width="24"
           height="24"

package/src/lib/components/popover-position.ts

@@ -0,0 +1,92 @@
+/**
+ * Pure positioning helper for `Popover.svelte`.
+ *
+ * Computes the viewport-coord `{ top, left }` for the panel given
+ * the trigger geometry, panel size, viewport size, and placement.
+ * Lives in its own module so the layout policy (which side wins on
+ * tight viewports, how flips clamp to the margin, etc.) is unit-
+ * testable without spinning up the Svelte component + jsdom.
+ *
+ * Auto-flip behaviour: the documented placements only mention
+ * `bottom-*`, but when the trigger sits near the bottom of the
+ * viewport (e.g. a pill on a session footer) the panel would open
+ * off-screen. We treat the placement's `bottom` half as a HINT
+ * rather than a hard rule \u2014 if the panel doesn't fit below AND
+ * there's more room above than below, we flip the vertical anchor
+ * to open upward. Horizontal alignment (`-start` / `-end` /
+ * centred) is preserved across the flip.
+ */
+
+export interface TriggerRect {
+  top: number
+  bottom: number
+  left: number
+  right: number
+  width: number
+}
+
+export type PopoverPlacement = 'bottom-start' | 'bottom-end' | 'bottom'
+
+export interface ComputePanelPositionInput {
+  triggerRect: TriggerRect
+  panelWidth: number
+  panelHeight: number
+  viewportWidth: number
+  viewportHeight: number
+  placement: PopoverPlacement
+  /** Gutter between the panel and the viewport edge on every side. */
+  margin: number
+  /** Gap between the trigger edge and the panel edge along the axis. */
+  offset: number
+}
+
+export interface PanelPosition {
+  top: number
+  left: number
+}
+
+export const computePanelPosition = (input: ComputePanelPositionInput): PanelPosition => {
+  const {
+    triggerRect,
+    panelWidth,
+    panelHeight,
+    viewportWidth,
+    viewportHeight,
+    placement,
+    margin,
+    offset,
+  } = input
+
+  // Horizontal: align per placement, then clamp into the viewport so
+  // edge-anchored triggers don't push the panel off-screen.
+  let left: number
+  if (placement === 'bottom-start') {
+    left = triggerRect.left
+  } else if (placement === 'bottom-end') {
+    left = triggerRect.right - panelWidth
+  } else {
+    left = triggerRect.left + triggerRect.width / 2 - panelWidth / 2
+  }
+  left = Math.max(margin, Math.min(left, viewportWidth - panelWidth - margin))
+
+  // Vertical: prefer below the trigger (documented behaviour). Flip
+  // above when:
+  //   1. the panel does NOT fit below (panel height + offset would
+  //      cross the bottom margin), AND
+  //   2. above has more room than below.
+  // When neither side fully fits, we still prefer the side with more
+  // breathing room \u2014 the panel then gets clamped to the viewport
+  // margin so its content scrolls instead of clipping at the edge.
+  const spaceBelow = viewportHeight - triggerRect.bottom - margin
+  const spaceAbove = triggerRect.top - margin
+  const fitsBelow = panelHeight + offset <= spaceBelow
+
+  let top: number
+  if (fitsBelow || spaceBelow >= spaceAbove) {
+    top = triggerRect.bottom + offset
+  } else {
+    top = Math.max(margin, triggerRect.top - offset - panelHeight)
+  }
+
+  return { top, left }
+}

package/src/lib/index.ts

@@ -20,6 +20,7 @@ export { default as TabPanel } from './components/TabPanel.svelte'
 export { default as Toggle } from './components/Toggle.svelte'
 export { default as RowToggle } from './components/RowToggle.svelte'
 export { default as Modal } from './components/Modal.svelte'
+export type { ModalSize } from './components/Modal.svelte'
 export { default as Sparkline } from './components/Sparkline.svelte'
 export { default as SparklineMatrix } from './components/SparklineMatrix.svelte'
 export type { SparklineMatrixRow } from './components/SparklineMatrix.svelte'
@@ -308,3 +309,5 @@ export { default as H3 } from './components/H3.svelte'
 export { default as H4 } from './components/H4.svelte'
 
 export * from './icons.js'
+
+export { portal } from './actions/portal.ts'