@stnd/ui 0.5.0

package/Panel.svelte

@@ -0,0 +1,365 @@
+<script>
+  /**
+   * @stnd/ui/Panel.svelte
+   * Edge Panel — a collapsible side panel fixed to the screen edge.
+   *
+   * Shows only a thin 6px handle strip by default. Clicking the handle slides
+   * the panel open. A pin button in the header locks it open so it won't close
+   * on outside clicks. Pin state is persisted to localStorage when `id` is set.
+   *
+   * @example
+   *   <Panel side="right" title="Inspector" id="inspector-panel" width="320px">
+   *     <p>Panel content here</p>
+   *   </Panel>
+   */
+  import { onMount } from "svelte";
+
+  /**
+   * @typedef {Object} PanelProps
+   * @property {'left' | 'right'} [side] - Which screen edge to attach to
+   * @property {string} [title] - Optional header title
+   * @property {string} [width] - Panel open width (CSS value)
+   * @property {string} [id] - Optional ID for localStorage pin persistence
+   * @property {import('svelte').Snippet} [children] - Panel body content
+   */
+
+  /** @type {PanelProps} */
+  let {
+    side = "right",
+    title = "",
+    width = "280px",
+    id = "",
+    children,
+  } = $props();
+
+  let open = $state(false);
+  let pinned = $state(false);
+
+  const storageKey = $derived(id ? `panel-pinned:${id}` : "");
+
+  onMount(() => {
+    if (storageKey) {
+      try {
+        pinned = localStorage.getItem(storageKey) === "true";
+        if (pinned) open = true;
+      } catch {
+        // localStorage unavailable (e.g. private browsing with storage blocked)
+      }
+    }
+  });
+
+  function toggleOpen() {
+    open = !open;
+    // Unpinning when closing
+    if (!open && pinned) {
+      pinned = false;
+      persistPin(false);
+    }
+  }
+
+  function togglePin() {
+    pinned = !pinned;
+    persistPin(pinned);
+  }
+
+  function closePanel() {
+    if (pinned) return;
+    open = false;
+  }
+
+  /** @param {boolean} value */
+  function persistPin(value) {
+    if (!storageKey) return;
+    try {
+      if (value) {
+        localStorage.setItem(storageKey, "true");
+      } else {
+        localStorage.removeItem(storageKey);
+      }
+    } catch {
+      // localStorage unavailable
+    }
+  }
+
+  function handleKeydown(/** @type {KeyboardEvent} */ e) {
+    if (e.key === "Escape" && open && !pinned) {
+      open = false;
+    }
+  }
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+
+<!-- Overlay: closes panel on outside click when open and not pinned -->
+{#if open && !pinned}
+  <div
+    class="panel-overlay"
+    onclick={closePanel}
+    role="presentation"
+    aria-hidden="true"
+  ></div>
+{/if}
+
+<div
+  class="panel-root"
+  class:side-left={side === "left"}
+  class:side-right={side === "right"}
+  class:is-open={open}
+  class:is-pinned={pinned}
+  style="--panel-width: {width}"
+>
+  <!-- Always-visible handle strip -->
+  <button
+    class="panel-handle"
+    onclick={toggleOpen}
+    aria-label={open ? "Close panel" : "Open panel"}
+    aria-expanded={open}
+  >
+    <span class="handle-line"></span>
+    <span class="handle-icon" aria-hidden="true">
+      <!-- Chevron: rotates based on side + open state via CSS -->
+      <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+        <polyline points="9 18 15 12 9 6"></polyline>
+      </svg>
+    </span>
+  </button>
+
+  <!-- Sliding body -->
+  <div class="panel-body" aria-hidden={!open}>
+    <div class="panel-header">
+      {#if title}
+        <span class="panel-title">{title}</span>
+      {/if}
+      <button
+        class="panel-pin"
+        class:is-pinned={pinned}
+        onclick={togglePin}
+        aria-label={pinned ? "Unpin panel" : "Pin panel open"}
+        aria-pressed={pinned}
+      >
+        {#if pinned}
+          <!-- Pinned: filled path -->
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="12" y1="17" x2="12" y2="22"/>
+            <path fill="currentColor" d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24Z"/>
+          </svg>
+        {:else}
+          <!-- Unpinned: outline only -->
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="12" y1="17" x2="12" y2="22"/>
+            <path d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24Z"/>
+          </svg>
+        {/if}
+      </button>
+    </div>
+
+    <div class="panel-content">
+      {@render children?.()}
+    </div>
+  </div>
+</div>
+
+<style>
+  /* ── Root ─────────────────────────────────────────────────── */
+
+  .panel-root {
+    --panel-handle-width: 6px;
+    --panel-z: 500;
+
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    z-index: var(--panel-z);
+    display: flex;
+    align-items: stretch;
+  }
+
+  .side-right {
+    right: var(--gap-body, 1.5rem);
+    flex-direction: row-reverse; /* handle on left, body on right */
+  }
+
+  .side-left {
+    left: var(--gap-body, 1.5rem);
+    flex-direction: row; /* handle on right, body on left */
+  }
+
+  /* ── Handle ───────────────────────────────────────────────── */
+
+  .panel-handle {
+    flex-shrink: 0;
+    width: var(--panel-handle-width);
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-d2, 0.25rem);
+    background: transparent;
+    border: none;
+    padding: 0;
+    cursor: pointer;
+    position: relative;
+    z-index: 1;
+    transition: background var(--transition, 200ms ease);
+
+    &:hover,
+    &:focus-visible {
+      background: oklch(from var(--color-foreground, currentColor) l c h / 0.06);
+      outline: none;
+
+      .handle-line {
+        opacity: 1;
+        background: var(--color-accent, currentColor);
+      }
+
+      .handle-icon {
+        opacity: 1;
+      }
+    }
+  }
+
+  .handle-line {
+    width: 2px;
+    height: 2rem;
+    border-radius: 999px;
+    background: oklch(from var(--color-foreground, currentColor) l c h / 0.25);
+    opacity: 0.6;
+    transition: background var(--transition, 200ms ease), opacity var(--transition, 200ms ease);
+  }
+
+  .handle-icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0.5;
+    color: var(--color-foreground, currentColor);
+    transition: opacity var(--transition, 200ms ease), transform var(--transition, 200ms ease);
+
+    /* Chevron points inward by default; flip based on side + open state */
+    .side-right & {
+      transform: rotate(180deg); /* points left (into the panel) */
+    }
+
+    .side-left & {
+      transform: rotate(0deg); /* points right (into the panel) */
+    }
+
+    /* When open, chevron reverses direction to indicate close */
+    .is-open.side-right & {
+      transform: rotate(0deg);
+    }
+
+    .is-open.side-left & {
+      transform: rotate(180deg);
+    }
+  }
+
+  /* Hide handle when pinned open (optional — gives more space) */
+  .is-pinned .panel-handle {
+    opacity: 0;
+    pointer-events: none;
+    width: 0;
+    overflow: hidden;
+  }
+
+  /* ── Panel body ───────────────────────────────────────────── */
+
+  .panel-body {
+    width: 0;
+    opacity: 0;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    background: var(--color-surface, white);
+    border-inline: 1px solid var(--border, rgba(0 0 0 / 0.1));
+    box-shadow: var(--shadow-raised, 0 4px 16px rgba(0 0 0 / 0.12));
+    backdrop-filter: var(--filter-blur, none);
+    transition:
+      width var(--transition, 200ms ease),
+      opacity var(--transition, 200ms ease);
+    /* Prevent content from wrapping during the slide-in transition */
+    min-width: 0;
+
+    .is-open & {
+      width: var(--panel-width, 280px);
+      opacity: 1;
+    }
+  }
+
+  /* ── Header ───────────────────────────────────────────────── */
+
+  .panel-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-d2, 0.25rem);
+    padding: var(--space, 1rem);
+    border-block-end: 1px solid var(--border, rgba(0 0 0 / 0.08));
+    flex-shrink: 0;
+    min-height: 2.75rem;
+  }
+
+  .panel-title {
+    font-family: var(--font-interface, sans-serif);
+    font-size: var(--size-sm, 0.875rem);
+    font-weight: 600;
+    color: var(--color-foreground, currentColor);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    flex: 1;
+  }
+
+  /* ── Pin button ───────────────────────────────────────────── */
+
+  .panel-pin {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 1.75rem;
+    height: 1.75rem;
+    border-radius: var(--radius, 6px);
+    border: none;
+    background: transparent;
+    color: oklch(from var(--color-foreground, currentColor) l c h / 0.4);
+    cursor: pointer;
+    transition:
+      background var(--transition, 200ms ease),
+      color var(--transition, 200ms ease);
+
+    &:hover,
+    &:focus-visible {
+      background: oklch(from var(--color-foreground, currentColor) l c h / 0.08);
+      color: var(--color-foreground, currentColor);
+      outline: none;
+    }
+
+    &.is-pinned {
+      color: var(--color-accent, currentColor);
+      background: oklch(from var(--color-accent, currentColor) l c h / 0.1);
+    }
+  }
+
+  /* ── Content ──────────────────────────────────────────────── */
+
+  .panel-content {
+    flex: 1;
+    overflow-y: auto;
+    overflow-x: hidden;
+    padding: var(--space, 1rem);
+    /* Prevent content reflow flash during width transition */
+    min-width: var(--panel-width, 280px);
+  }
+
+  /* ── Overlay ──────────────────────────────────────────────── */
+
+  .panel-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 498;
+    background: transparent;
+    cursor: default;
+  }
+</style>

package/README.md

@@ -0,0 +1,150 @@
+---
+title: "@stnd/ui"
+aliases: []
+created: 2026-07-05 07:47
+modified: 2026-07-05 19:15
+last_audited: 2026-07-14
+audit_interval_days: 90
+next_audit: 2026-10-12
+audit_priority: 3
+maturity: sprout
+mode: read
+publish: false
+status: active
+tags:
+  - package
+  - stnd
+theme: kernel
+type: package
+visibility: private
+---
+
+# @[stnd](../README)/ui
+
+Shared UI components for the Standard Ecosystem.
+
+---
+
+Most buttons/badges/cards should just be a CSS class on plain HTML (see `@stnd/styles`) — no JS, no import. This package is only for the handful of things that genuinely need interactivity: a dropdown that manages keyboard navigation, a confirm dialog you can `await`, a right-click menu. If you’re reaching for a component here and it’s not doing something stateful or ARIA-heavy, check whether a CSS class already does the job.
+
+**Use it (the confirm dialog, the most common one):**
+
+```javascript
+import { confirm } from "@stnd/ui/dialog.js";
+const ok = await confirm({ title: "Delete this?", intent: "danger" });
+```
+
+## Overview
+
+`@stnd/ui` provides a collection of reusable, accessible, and high-quality UI components built for Astro and Svelte 5. These components are designed to work seamlessly with `@stnd/styles` and follow the Standard design principles.
+
+## 🏛 The Philosophy: CSS First, Components Second
+
+Standard is built on the philosophy of keeping the codebase as clean, fast, and static as possible. Before importing a component from `@stnd/ui`, ask yourself: **Can this be done with just HTML and `@stnd/styles`?**
+
+Many UI elements you see in the Playground (like Buttons, Badges, Cards, and Inputs) are **not components**. They are simple CSS classes applied to standard HTML elements.
+
+**Why?**
+- Zero JavaScript overhead.
+- Perfect semantic HTML.
+- Maximum flexibility without passing dozens of props.
+
+### Example: Buttons & Badges (CSS Only)
+You do not need a `<Button>` or `<Badge>` component. Just use the global classes provided by `@stnd/styles`:
+
+```html
+<!-- Primary Button -->
+<button class="btn">Save Changes</button>
+
+<!-- Ghost Button -->
+<button class="btn ghost">Cancel</button>
+
+<!-- Success Badge -->
+<span class="badge success">Active</span>
+```
+
+### When to use `@stnd/ui` Components?
+You should only import components from this package when you need:
+1. **Complex interactivity** (e.g., `Dropdown`, `ContextMenu`).
+2. **State management** (e.g., `DialogManager`, `ComboBox`).
+3. **Advanced Accessibility / ARIA management** (e.g., `Accordion`).
+4. **Complex composition** (e.g., `Accordion`, `Scroller`, `TableOfContents`).
+
+> Icons and Lottie animations are **not** in this package — they live in
+> `@stnd/icon` (`import Icon from "@stnd/icon/Icon.astro"`). See its README.
+
+---
+
+## 🧩 Component API Reference
+
+### Astro Components (Zero JS)
+
+#### `<Accordion />`
+Accessible, collapsible content sections.
+- `open` (boolean): Sets the initial open state.
+
+---
+
+### Svelte 5 Components (Hydrated)
+
+#### `<Alert />`
+Semantic feedback banners.
+- `class` (string): The semantic intent: `success`, `warning`, `error`, `info`. (Defaults to accent color).
+- `title` (string): Optional bold title.
+- `icon` (string): Optional string icon (e.g., `✓`, `⚠`).
+
+```svelte
+<Alert class="warning" title="Watch out!" icon="⚠">
+  This action cannot be undone.
+</Alert>
+```
+
+#### `<Dropdown />`
+Accessible, keyboard-navigable dropdown menus.
+- `align` (string): Alignment of the menu (`start`, `center`, `end`). Defaults to `start`.
+- **Slots**: `trigger` (the button that opens the menu), `default` (the menu items).
+
+**Related Sub-components**:
+- `<DropdownItem icon="ph:user" shortcut="⌘P">Profile</DropdownItem>`
+- `<DropdownLabel label="My Account" />`
+- `<DropdownSeparator />`
+
+#### `<ContextMenu />`
+Viewport-aware right-click menus.
+- **Slots**: `default` (the area that triggers the menu on right-click), `content` (the menu items).
+
+---
+
+## 🚨 Dialog Manager
+
+The `DialogManager` allows you to trigger accessible confirmation dialogs programmatically from any script using a simple Promise-based API. This prevents littering your DOM with hidden modal HTML.
+
+### 1. Mount the Manager
+Ensure `<DialogManagerComponent client:load />` is mounted once in your root layout (Standard does this by default).
+
+### 2. Call the API
+
+```javascript
+import { confirm } from "@stnd/ui/dialog.js";
+
+const isConfirmed = await confirm({
+  title: "Delete this item?",
+  description: "This action cannot be undone. Are you sure?",
+  confirmLabel: "Yes, Delete",
+  cancelLabel: "Cancel",
+  intent: "danger" // "neutral" | "danger"
+});
+
+if (isConfirmed) {
+  // Proceed with deletion
+}
+```
+
+## Notes / Observations
+
+*(jot down anything noticed here — quirks, gotchas, ideas)*
+
+## Todo
+
+- [ ] **README is thin relative to the component count** — `Combobox`, [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]
+      `Panel`, `Pagination`, `Scroller`, `TableOfContents`, `Toast`, `CfImage`,       `LauncherHint` exist on disk but aren’t documented above. Worth a pass       once this package settles.

package/Scroller.astro

@@ -0,0 +1,11 @@
+---
+/**
+ * Scroller.astro
+ *
+ * Astro wrapper for Scroller.svelte that ensures it always hydrates on load.
+ * Usage: <Scroller /> (no client:load needed)
+ */
+import SvelteScroller from "./Scroller.svelte";
+---
+
+<SvelteScroller client:load />

package/Scroller.svelte

@@ -0,0 +1,44 @@
+<script>
+  let progress = $state(0);
+
+  function updateProgress() {
+    const scrollTop = window.scrollY;
+    const docHeight =
+      document.documentElement.scrollHeight - window.innerHeight;
+    progress = (scrollTop / docHeight) * 100;
+  }
+
+  $effect(() => {
+    window.addEventListener("scroll", updateProgress);
+    return () => {
+      window.removeEventListener("scroll", updateProgress);
+    };
+  });
+</script>
+
+<div class="progress-container">
+  <div class="progress-bar" style="width: {progress}%"></div>
+</div>
+
+<style>
+  .progress-container {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: var(--stroke-width-lg);
+    z-index: 999999999;
+    pointer-events: none;
+    margin-top: 0 !important;
+  }
+
+  .progress-bar {
+    height: 100%;
+    background-color: oklch(from var(--color-foreground) l c h / 0.15);
+    backdrop-filter: var(--filter-glass);
+    box-shadow: var(--shadow-lg) !important;
+    transition: width var(--transition-fast);
+    border-radius: var(--radius);
+    margin-top: 0 !important;
+  }
+</style>