@thespielplatz/tsp-tools-theme 0.2.1 → 0.3.1

package/components/TspNavSection.vue

@@ -0,0 +1,33 @@
+<!--
+  A break in the nav: a rule, optionally followed by a small label.
+
+    <TspNavSection label="External" />   rule + label
+    <TspNavSection />                    bare divider
+
+  The label deliberately shares the sidebar footer's `User` treatment — 10px,
+  uppercase, muted — so a section header reads the same wherever it appears
+  (spec 04).
+-->
+<template>
+  <div
+    data-testid="tsp-nav-section"
+    :data-bare="!label"
+    class="mt-3 shrink-0"
+  >
+    <hr class="border-default">
+    <p
+      v-if="label"
+      data-testid="tsp-nav-section-label"
+      class="px-3 mt-3 mb-1 text-[10px] uppercase tracking-wide text-muted"
+    >
+      {{ label }}
+    </p>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** Omit for a bare divider. */
+  label?: string
+}>()
+</script>

package/components/TspNavSubItem.vue

@@ -0,0 +1,35 @@
+<!--
+  A child row inside a TspNavGroup. Carries its own icon, in its own indented
+  column — the level is already carried by the indent, the spine and the muting,
+  so the icon does not have to do that work too.
+
+  Muted at rest against the parent's white (spec 04, reading 2), amber when it
+  is the current route — amber means "you are here" at every level. The icon
+  inherits the row colour rather than setting its own, so it follows through
+  rest, hover and active without three rules. Children are the narrowest rows in
+  the sidebar, so they get the same hover reveal as their parents.
+-->
+<template>
+  <NuxtLink
+    :to="to"
+    data-testid="tsp-nav-sub-item"
+    class="group relative flex shrink-0 items-center gap-2.5 h-8 px-3 rounded-md text-sm font-normal text-muted hover:text-highlighted hover:bg-default"
+    active-class="tsp-text-brand"
+  >
+    <UIcon
+      v-if="icon"
+      :name="icon"
+      class="text-lg"
+    />
+    <TspNavLabel><slot /></TspNavLabel>
+  </NuxtLink>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** Internal route. A child row is always internal. */
+  to: string
+  /** Tabler icon name, e.g. `i-tabler-list-details`. */
+  icon?: string
+}>()
+</script>

package/components/TspPageTabs.vue

@@ -0,0 +1,46 @@
+<!--
+  Tabs across the top of an area, above the page title — the shape trips uses
+  for Settings / MCP Server.
+
+    <TspPageTabs :items="[
+      { label: 'Settings', to: '/settings', icon: 'i-tabler-adjustments' },
+      { label: 'MCP Server', to: '/settings/mcp', icon: 'i-tabler-plug' },
+    ]" />
+
+  ROUTES, not local state: these are pages, so each tab is a link and the
+  browser's back button works. For switching views WITHIN one page, use plain
+  buttons — see /content.
+
+  Active is amber TEXT plus an underline, using `.tsp-text-brand` rather than
+  `text-primary`, so it steps down to amber-600 on light where #fbad18 fails as
+  text. Same rule as the active nav item (ADR 018).
+-->
+<template>
+  <nav
+    data-testid="tsp-page-tabs"
+    class="flex gap-6 border-b border-default mb-8 overflow-x-auto tsp-scroll-quiet"
+  >
+    <NuxtLink
+      v-for="item in items"
+      :key="item.to"
+      :to="item.to"
+      data-testid="tsp-page-tab"
+      class="-mb-px flex shrink-0 items-center gap-1.5 border-b-2 border-transparent pb-2.5 text-sm font-bold text-muted transition-colors hover:text-highlighted"
+      active-class="!border-current tsp-text-brand"
+    >
+      <UIcon
+        v-if="item.icon"
+        :name="item.icon"
+        class="text-base"
+      />
+      {{ item.label }}
+    </NuxtLink>
+  </nav>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** One entry per view: `{ label, to, icon? }`. `to` is a ROUTE, so the back button works. */
+  items: { label: string, to: string, icon?: string }[]
+}>()
+</script>

package/components/TspReleaseNotes.vue

@@ -0,0 +1,143 @@
+<!--
+  Release notes for one or more versions — the overview the tsp-release skill
+  writes, rendered.
+
+  The shape mirrors that skill exactly, so an app passes its RELEASES array
+  straight in rather than mapping it:
+
+    { version, date, showBanner?, showPopup?, important?: Item[], other?: Item[] }
+    Item = string | { text, compare?: { before, after }, beforeImage?, afterImage? }
+
+  `important` and `other` are separated because they are read differently: the
+  first is what made the release worth announcing, the second is what a curious
+  reader wants after that. Flattening them into one list loses the editorial
+  judgement the skill asked a human to make.
+
+  This renders the SAME content in the page and in the modal. Two renderings
+  would drift, and the drift would be invisible until someone compared them.
+-->
+<template>
+  <div class="flex flex-col gap-8">
+    <article
+      v-for="entry in releases"
+      :key="entry.version"
+      data-testid="tsp-release-entry"
+    >
+      <header class="flex items-baseline gap-3">
+        <h3 class="text-base font-bold text-highlighted">
+          {{ entry.version }}
+        </h3>
+        <time
+          v-if="entry.date"
+          :datetime="entry.date"
+          class="text-xs text-dimmed"
+        >{{ entry.date }}</time>
+      </header>
+
+      <template
+        v-for="group in groups"
+        :key="group.key"
+      >
+        <div v-if="entry[group.key]?.length">
+          <p class="mt-4 mb-2 text-xs font-bold uppercase tracking-wide text-muted">
+            {{ group.key === 'important' ? importantLabel : otherLabel }}
+          </p>
+          <ul class="flex flex-col gap-3">
+            <li
+              v-for="(item, i) in entry[group.key]"
+              :key="i"
+              data-testid="tsp-release-item"
+              class="flex gap-2.5 text-sm text-muted"
+            >
+              <UIcon
+                :name="group.icon"
+                class="mt-0.5 shrink-0 text-base"
+                :class="group.key === 'important' ? 'tsp-text-brand' : 'text-dimmed'"
+              />
+              <div class="min-w-0">
+                <p>{{ text(item) }}</p>
+
+                <!-- before/after, as the skill's `compare` captions -->
+                <div
+                  v-if="compare(item)"
+                  data-testid="tsp-release-compare"
+                  class="mt-2 grid gap-2 sm:grid-cols-2"
+                >
+                  <div
+                    v-for="side in (['before', 'after'] as const)"
+                    :key="side"
+                    class="rounded-md border border-default p-3"
+                  >
+                    <p
+class="mb-1 text-[10px] font-bold uppercase tracking-wide"
+                      :class="side === 'after' ? 'tsp-text-brand' : 'text-dimmed'"
+                    >
+                      {{ side === 'before' ? beforeLabel : afterLabel }}
+                    </p>
+                    <img
+                      v-if="image(item, side)"
+                      :src="image(item, side)"
+                      :alt="`${side}: ${text(item)}`"
+                      class="mb-2 w-full rounded-sm border border-default"
+                    >
+                    <p class="text-xs text-dimmed">
+                      {{ compare(item)?.[side] }}
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </li>
+          </ul>
+        </div>
+      </template>
+    </article>
+  </div>
+</template>
+
+<script setup lang="ts">
+export interface TspReleaseItemObject {
+  text: string
+  compare?: { before: string, after: string }
+  beforeImage?: string
+  afterImage?: string
+}
+export type TspReleaseItem = string | TspReleaseItemObject
+export interface TspRelease {
+  version: string
+  date?: string
+  showBanner?: boolean
+  showPopup?: boolean
+  important?: TspReleaseItem[]
+  other?: TspReleaseItem[]
+}
+
+withDefaults(defineProps<{
+  /** Newest first. Mirrors the `tsp-release` skill's RELEASES shape, so a service can pass its
+   * own array straight through.
+   */
+  releases: TspRelease[]
+  /** Heading over the `important` items. */
+  importantLabel?: string
+  /** Heading over the `other` items. */
+  otherLabel?: string
+  /** Caption on the left side of a before/after pair. */
+  beforeLabel?: string
+  /** Caption on its right side. */
+  afterLabel?: string
+}>(), {
+  importantLabel: 'Highlights',
+  otherLabel: 'Also in this release',
+  beforeLabel: 'Before',
+  afterLabel: 'After',
+})
+
+const groups = [
+  { key: 'important' as const, icon: 'i-tabler-sparkles' },
+  { key: 'other' as const, icon: 'i-tabler-point' },
+]
+
+const text = (i: TspReleaseItem) => (typeof i === 'string' ? i : i.text)
+const compare = (i: TspReleaseItem) => (typeof i === 'string' ? undefined : i.compare)
+const image = (i: TspReleaseItem, side: 'before' | 'after') =>
+  (typeof i === 'string' ? undefined : side === 'before' ? i.beforeImage : i.afterImage)
+</script>

package/components/TspSectionCard.vue

@@ -0,0 +1,52 @@
+<!--
+  A titled content card: icon + title in a header row, content below.
+
+    <TspSectionCard icon="i-tabler-server" title="MCP Server"> … </TspSectionCard>
+
+  This is the shape trips uses on its settings pages and it generalises: an
+  icon and a short title make a card say what it is without a heading competing
+  with the page title above it.
+
+  Sits on `bg-elevated` — the raised CONTENT surface, distinct from the shell's
+  `bg-muted`. And `rounded-xl`, written here rather than left to Nuxt UI's
+  `rounded-lg`, because this IS the layer's card and the 12px rule applies.
+
+  No cards inside cards (ADR 018): the code block and fields it holds are
+  bordered, not filled a second time.
+-->
+<template>
+  <section
+    data-testid="tsp-section-card"
+    class="rounded-xl border border-default bg-elevated p-5"
+  >
+    <div
+      v-if="title || icon"
+      class="flex items-center gap-2 mb-4"
+    >
+      <UIcon
+        v-if="icon"
+        :name="icon"
+        class="text-lg shrink-0 tsp-text-brand"
+      />
+      <!-- Gated too: the wrapper allows an icon-only card, which would
+           otherwise emit an empty <h2> that heading navigation lands on. -->
+      <h2
+        v-if="title"
+        data-testid="tsp-section-card-title"
+        class="text-sm font-bold text-highlighted"
+      >
+        {{ title }}
+      </h2>
+    </div>
+    <slot />
+  </section>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** Short card title. Omit for an untitled card — no empty heading is emitted. */
+  title?: string
+  /** Tabler icon name. Amber, because it labels rather than decorates. */
+  icon?: string
+}>()
+</script>

package/components/TspSidebar.vue

@@ -5,9 +5,52 @@
     #brand  — wordmark / logo (inside an inset bottom-bordered header)
     #nav    — TspNavItem links
     #footer — typically <TspSidebarFooter>
+
+  STICKY at `sm` and above: exactly the viewport's height, pinned to the top.
+  Without that it is a flex child of a `min-h-svh` row, so on a long page it
+  grows to the DOCUMENT's height and the footer rows — settings, logout, theme,
+  language — scroll away with the content. Navigation that leaves the screen is
+  not navigation.
+
+  RESPONSIVE. At `sm` and above it is an ordinary column. Below `sm` it becomes
+  an off-canvas drawer over a backdrop, opened by <TspTopBar>'s burger through
+  useTspNavDrawer(). 640px is the breakpoint the platform's own mockup already
+  used, so services that hand-built a drawer match.
+
+  The nav scrolls when it has to, with no visible scrollbar (`tsp-scroll-quiet`)
+  — a track beside 32px rows in a 224px column is clutter. Rows carry `shrink-0`
+  and the nav `min-h-0`: in a fixed-height column an overflowing flex child
+  shrinks by default, which silently squashed 32px rows to 23px once the
+  sidebar stopped growing with the page.
+
+  Fallthrough attrs are bound explicitly to the <aside>: this template has two
+  roots (backdrop + aside), and Vue cannot auto-inherit onto a fragment, so a
+  consumer's `class` was being dropped silently.
+
+  The drawer closes on backdrop click, on Escape, on leaving mobile, and ON
+  ROUTE CHANGE — a drawer
+  that survives navigation is the classic mobile bug: you tap a link, the page
+  behind changes, and the menu is still sitting on top of it.
 -->
 <template>
-  <aside class="flex flex-col w-56 shrink-0 bg-elevated border-r border-default py-5">
+  <div
+    v-if="isOpen"
+    data-testid="tsp-nav-backdrop"
+    class="sm:hidden fixed inset-0 z-40 bg-black/50"
+    @click="close"
+  />
+
+  <aside
+    id="tsp-sidebar"
+    v-bind="$attrs"
+    data-testid="tsp-sidebar"
+    :inert="mobileHidden"
+    class="flex flex-col w-56 shrink-0 bg-muted border-r border-default py-5
+           sm:sticky sm:top-0 sm:h-svh
+           max-sm:fixed max-sm:inset-y-0 max-sm:left-0 max-sm:z-50 max-sm:transition-transform"
+    :class="isOpen ? 'max-sm:translate-x-0' : 'max-sm:-translate-x-full'"
+    :aria-hidden="mobileHidden"
+  >
     <div
       v-if="$slots.brand"
       class="mx-2 px-2 pb-4 mb-3 border-b border-default"
@@ -15,12 +58,62 @@
       <slot name="brand" />
     </div>
 
-    <nav class="flex flex-col gap-0.5 px-2">
+    <nav class="flex min-h-0 flex-col gap-0.5 px-2 overflow-y-auto tsp-scroll-quiet">
       <slot name="nav" />
     </nav>
 
-    <div class="mt-auto px-3 pt-3">
+    <div class="mt-auto shrink-0 px-3 pt-3">
       <slot name="footer" />
     </div>
   </aside>
 </template>
+
+<script setup lang="ts">
+defineOptions({ inheritAttrs: false })
+
+const { isOpen, close } = useTspNavDrawer()
+const route = useRoute()
+
+watch(() => route.fullPath, close)
+
+// Off-screen is not the same as hidden: a translated-away drawer is still in
+// the tab order and still read aloud. Only applies below `sm`, so it is tracked
+// against the viewport rather than assumed.
+const isMobile = ref(false)
+const mobileHidden = computed(() => (isMobile.value && !isOpen.value ? 'true' : undefined))
+
+onMounted(() => {
+  const mq = window.matchMedia('(max-width: 639px)')
+  const sync = () => {
+    isMobile.value = mq.matches
+    // Leaving mobile with the drawer open would otherwise strand it: visually
+    // gone, still "open", still holding the scroll lock.
+    if (!mq.matches) close()
+  }
+  sync()
+  mq.addEventListener('change', sync)
+  onUnmounted(() => mq.removeEventListener('change', sync))
+
+  const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') close() }
+  window.addEventListener('keydown', onKey)
+  onUnmounted(() => window.removeEventListener('keydown', onKey))
+})
+
+// A drawer over the page should not let the page scroll behind it.
+const setBodyScroll = (locked: boolean) => {
+  if (import.meta.client) document.body.style.overflow = locked ? 'hidden' : ''
+}
+
+// Keyed on BOTH. Keyed on isOpen alone, widening past `sm` with the drawer
+// open left <body> locked forever: the drawer and backdrop are sm:hidden, so
+// they vanish, the watcher never re-fires, and the page cannot scroll with no
+// control left to unlock it.
+watch([isOpen, isMobile], ([open, mobile]) => setBodyScroll(open && mobile))
+
+// Released on unmount as well as on close. A layout swap or an HMR reload while
+// the drawer is open would otherwise leave `overflow: hidden` on <body>
+// forever, and the page could never scroll again.
+onUnmounted(() => {
+  if (isOpen.value) setBodyScroll(false)
+})
+</script>