@thespielplatz/tsp-tools-theme 0.2.0 → 0.3.0

package/components/TspTopBar.vue

@@ -0,0 +1,69 @@
+<!--
+  Mobile top bar — only below `sm`, where the sidebar has become a drawer.
+
+    burger · mark + wordmark · page title
+
+  Sticky: on mobile this bar is the only way to reach the nav, so it stays put
+  for the same reason the sidebar does on desktop.
+
+  THE BURGER IS ON THE LEFT, where the drawer comes from. stash puts it right;
+  the platform's own mockup and the other tsp services put it left, and a
+  control that opens a left drawer belongs on the left. stash is the outlier.
+
+  The page title matters more here than anywhere else: on mobile the sidebar is
+  hidden, so without it nothing on screen says where you are.
+-->
+<template>
+  <header
+    data-testid="tsp-top-bar"
+    class="sm:hidden sticky top-0 z-30 flex items-center gap-3 h-14 px-4 border-b border-default bg-muted"
+  >
+    <button
+      type="button"
+      data-testid="tsp-burger"
+      :aria-label="menuLabel"
+      :aria-expanded="isOpen"
+      aria-controls="tsp-sidebar"
+      class="flex size-9 shrink-0 items-center justify-center rounded-md border border-default text-muted hover:text-highlighted"
+      @click="toggle"
+    >
+      <UIcon
+        name="i-tabler-menu-2"
+        class="text-xl"
+      />
+    </button>
+
+    <slot name="brand" />
+
+    <span
+      v-if="pageTitle"
+      data-testid="tsp-top-bar-title"
+      class="ml-auto truncate text-sm font-bold text-highlighted"
+    >{{ pageTitle }}</span>
+  </header>
+</template>
+
+<script setup lang="ts">
+const props = withDefaults(defineProps<{
+  /** The current page's name. Nothing else on a mobile screen says where you are.
+      Omitted, it is derived from the route. */
+  title?: string
+  /** Accessible name for the burger button. */
+  menuLabel?: string
+}>(), {
+  title: undefined,
+  menuLabel: 'Open menu',
+})
+
+const { isOpen, toggle } = useTspNavDrawer()
+const route = useRoute()
+
+// Falls back to the route when no title is passed: `meta.title` if the page set
+// one, else the last path segment capitalised. Both demo apps had derived this
+// identically in their own layouts, which is a sign it belongs to the component
+// that renders it. An app with better titles passes `title` and this never runs.
+const pageTitle = computed(() => props.title
+  ?? (route.meta.title as string | undefined)
+  ?? route.path.split('/').filter(Boolean).pop()?.replace(/^\w/, c => c.toUpperCase())
+  ?? undefined)
+</script>

package/components/TspUserCard.vue

@@ -0,0 +1,127 @@
+<!--
+  The account card on a service's user page — rebuilt from stash, which already
+  runs this layout, so the layer now owns it instead of each service copying it
+  (ADR 017: the shell lives here).
+
+    <TspUserCard
+      name="Fil"
+      :account-id="user.id"
+      manage-link="https://auth.tsp.tools/account"
+    />
+
+  The layer has no auth and no data: the name, the id and the manage URL are the
+  app's. What lives here is the arrangement — amber mark, name over the account
+  line, the labelled id with its reveal, and the manage link.
+
+  MASKING IS REAL, NOT COSMETIC. While hidden, the id is simply not rendered;
+  the dots are a placeholder string. Covering the value with CSS would leave it
+  in the page source, copyable and readable by anything walking the DOM, which
+  is not masking — it just looks like it.
+
+  Every visible string is a prop with an English default (ADR 008, finding 4).
+
+  IT DOES NOT CAP ITS OWN WIDTH. It used to carry `max-w-lg`, which left the
+  user page 512px wide inside a 1152px column while every other page ran the
+  full measure. Page width belongs to <TspContainer>; a component that caps its
+  own root overrides it from the inside, and the app cannot undo it without
+  fighting tailwind-merge. A service that wants it narrower wraps it.
+-->
+<template>
+  <div
+    data-testid="tsp-user-card"
+    class="rounded-xl bg-elevated border border-default p-6"
+  >
+    <div class="flex items-center gap-4">
+      <UIcon
+        name="i-tabler-user-circle"
+        class="text-4xl shrink-0 tsp-text-brand"
+      />
+      <div class="min-w-0">
+        <p
+          data-testid="tsp-user-card-name"
+          class="font-bold text-highlighted truncate"
+        >
+          {{ name }}
+        </p>
+        <p
+          data-testid="tsp-user-card-account"
+          class="text-xs text-muted truncate"
+        >
+          {{ accountLabel }}
+        </p>
+      </div>
+    </div>
+
+    <template v-if="accountId">
+      <p class="mt-6 text-xs font-bold text-toned">
+        {{ idLabel }}
+      </p>
+      <div class="mt-1 flex items-center gap-2">
+        <code
+          data-testid="tsp-user-card-id"
+          class="text-sm text-muted tracking-wider"
+        >{{ revealed ? accountId : mask }}</code>
+        <button
+          type="button"
+          data-testid="tsp-user-card-reveal"
+          :aria-pressed="revealed"
+          :aria-label="revealed ? hideLabel : revealLabel"
+          :title="revealed ? hideLabel : revealLabel"
+          class="rounded-md p-1 text-muted hover:text-highlighted hover:bg-default"
+          @click="toggle"
+        >
+          <UIcon
+            :name="revealed ? 'i-tabler-eye-off' : 'i-tabler-eye'"
+            class="text-base block"
+          />
+        </button>
+      </div>
+    </template>
+
+    <a
+      v-if="manageLink"
+      data-testid="tsp-user-card-manage"
+      :href="manageLink"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="mt-6 inline-flex items-center gap-1.5 text-sm font-bold tsp-text-brand hover:underline"
+    >
+      {{ manageLabel }}
+      <UIcon
+        name="i-tabler-external-link"
+        class="text-base"
+      />
+    </a>
+  </div>
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  /** Display name. */
+  name: string
+  /** Which account this is — shown under the name. */
+  accountLabel?: string
+  /** The account id. Omit to hide the whole id block. */
+  accountId?: string
+  /** Label over the account id. */
+  idLabel?: string
+  /** Where “manage account” goes. Omit to hide the link. */
+  manageLink?: string
+  /** Text of the manage-account link. */
+  manageLabel?: string
+  /** Accessible name for the eye while the id is hidden. */
+  revealLabel?: string
+  /** Accessible name for it while the id is shown. */
+  hideLabel?: string
+}>(), {
+  accountLabel: 'tsp.tools account',
+  accountId: undefined,
+  idLabel: 'tsp.tools ID',
+  manageLink: undefined,
+  manageLabel: 'Manage account in Logto',
+  revealLabel: 'Show ID',
+  hideLabel: 'Hide ID',
+})
+
+const { revealed, toggle, mask } = useTspReveal(12)
+</script>

package/components/TspVersionBadge.vue

@@ -0,0 +1,49 @@
+<!--
+  The version pill in the sidebar footer. A link when `href` is given, plain
+  text otherwise (spec 03) — a closed-source project has no release page to
+  point at, so its badge must not look clickable.
+
+  Carries a tag icon (spec 05 item 3), which is also what tells it apart from
+  the role pills now that both are outlined rounded-full shapes.
+
+  `unread` marks that there are release notes the user has not seen — the
+  tsp-release skill writes those notes, and the badge is where a user looks for
+  the version anyway, so it is the honest place to say "this changed". It goes
+  amber TEXT with an amber edge, not an amber fill: a filled pill in the sidebar
+  is what ADR 018 removed. Whether a release counts as unread is the app's
+  question, not the layer's.
+
+  Kept as its own component because it appears in two places: beside the theme
+  toggle when the project is closed source, and on the GitHub row when it is
+  open source.
+-->
+<template>
+  <component
+    :is="href ? 'a' : 'span'"
+    data-testid="tsp-version-badge"
+    v-bind="href ? { href, target: '_blank', rel: 'noopener noreferrer' } : {}"
+    :data-unread="unread ? 'true' : undefined"
+    class="inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs"
+    :class="[
+      unread ? 'tsp-text-brand border-current' : 'border-default text-muted',
+      href ? 'hover:text-highlighted hover:border-accented' : '',
+    ]"
+  >
+    <UIcon
+      name="i-tabler-tag"
+      class="text-xs shrink-0"
+    />
+    {{ version }}
+  </component>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** The version string, shown as-is, e.g. `v0.3.0`. */
+  version: string
+  /** Release link. Omitted for closed-source projects, which renders a span. */
+  href?: string
+  /** There are release notes the user has not seen. */
+  unread?: boolean
+}>()
+</script>

package/components/TspWordmark.vue

@@ -1,9 +1,41 @@
 <!--
-  Brand wordmark in Space Grotesk + amber. Put the app name (and optional logo)
-  in the default slot, e.g. <TspWordmark>trips<span class="text-primary">.</span></TspWordmark>.
+  Brand wordmark: the app's name in white, terminated by an amber dot.
+
+    <TspWordmark name="trips" />   →  trips.
+    <TspWordmark name="gage" />    →  gage.
+
+  THE COMPONENT OWNS THE DOT (spec 03). There is no slot: the one case that
+  argued for one was `tsp.tools`, and that turned out not to be a wordmark at
+  all — it is the domain of the whole tool set, not a tool's name. Keeping an
+  escape hatch for a case nobody has would only let the old mid-dot form
+  (`tsp` · amber `.` · `tools`) back in.
+
+  Before 0.3.0 the root carried `text-primary`, so the WHOLE mark rendered amber
+  and the amber-dot span this component's own docs prescribed was a no-op. The
+  documented format was never actually possible.
+
+  The dot uses `.tsp-text-brand`, not `text-primary`, so it steps down to
+  amber-600 on light surfaces where #fbad18 fails contrast — same treatment as
+  the active nav item (ADR 018).
 -->
 <template>
-  <div class="tsp-wordmark font-bold text-xl tracking-tight text-primary">
-    <slot />
+  <div
+    data-testid="tsp-wordmark"
+    class="tsp-wordmark font-bold text-xl tracking-tight"
+  >
+    <span
+      data-testid="tsp-wordmark-name"
+      class="text-highlighted"
+    >{{ name }}</span><span
+      data-testid="tsp-wordmark-dot"
+      class="tsp-text-brand"
+    >.</span>
   </div>
 </template>
+
+<script setup lang="ts">
+defineProps<{
+  /** The app name, lowercase. The amber dot is appended for you. */
+  name: string
+}>()
+</script>

package/composables/useTspCopy.ts

@@ -0,0 +1,72 @@
+/**
+ * Copy text to the clipboard and confirm it for a moment.
+ *
+ * `navigator.clipboard` needs a SECURE CONTEXT. It is absent over plain HTTP on
+ * a LAN address, which is exactly how a service gets tested on a phone — so the
+ * fallback keeps the button working there instead of failing silently.
+ *
+ * `copied` returns to false on its own; a copy that gives no feedback gets
+ * pressed twice.
+ */
+export const useTspCopy = (resetDelay = 1600) => {
+  const copied = ref(false)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let alive = true
+
+  const legacyCopy = (text: string) => {
+    const ta = document.createElement('textarea')
+    ta.value = text
+    // readonly stops a mobile keyboard appearing for the split second the
+    // textarea is focused; inert/aria-hidden keep it out of the tab order and
+    // off the accessibility tree while it briefly exists.
+    ta.setAttribute('readonly', '')
+    ta.setAttribute('aria-hidden', 'true')
+    ta.tabIndex = -1
+    ta.style.cssText = 'position:fixed;top:-9999px;opacity:0'
+    document.body.appendChild(ta)
+    try {
+      ta.select()
+      // execCommand returns FALSE without throwing when the copy is refused —
+      // which is precisely the plain-HTTP case this fallback exists for. The
+      // return value used to be discarded, so the tick appeared while the
+      // clipboard was untouched.
+      return document.execCommand('copy')
+    }
+    finally {
+      // `finally`, not the happy path: a throw here used to leave a textarea
+      // holding the real secret in the DOM for the rest of the session —
+      // CSS-covered and readable by anything walking it, which is exactly what
+      // this layer's masking rule says is not masking.
+      ta.value = ''
+      ta.remove()
+    }
+  }
+
+  const copy = async (text: string) => {
+    try {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text)
+      }
+      else if (!legacyCopy(text)) {
+        copied.value = false
+        return
+      }
+      // The await above can resolve after the component is gone; scheduling a
+      // timer then would outlive the cleanup that was supposed to clear it.
+      if (!alive) return
+      copied.value = true
+      clearTimeout(timer)
+      timer = setTimeout(() => { copied.value = false }, resetDelay)
+    }
+    catch {
+      copied.value = false
+    }
+  }
+
+  onUnmounted(() => {
+    alive = false
+    clearTimeout(timer)
+  })
+
+  return { copied, copy }
+}

package/composables/useTspNavDrawer.ts

@@ -0,0 +1,14 @@
+// Shared open/closed state for the mobile nav drawer, so TspTopBar's burger and
+// TspSidebar do not have to be wired together by every app.
+//
+// useState, not a module-level ref: on the server a module-level ref is shared
+// across requests, which leaks one visitor's open drawer into another's page.
+export const useTspNavDrawer = () => {
+  const isOpen = useState('tsp-nav-drawer', () => false)
+
+  const open = () => { isOpen.value = true }
+  const close = () => { isOpen.value = false }
+  const toggle = () => { isOpen.value = !isOpen.value }
+
+  return { isOpen, open, close, toggle }
+}

package/composables/useTspReveal.ts

@@ -0,0 +1,18 @@
+/**
+ * Show/hide a secret, with the placeholder to render while it is hidden.
+ *
+ * MASKING IS REAL, NOT COSMETIC: callers render `mask` INSTEAD of the value,
+ * never the value under a CSS cover. A covered value is still in the page
+ * source, still copyable, and still readable by anything walking the DOM — that
+ * is not masking, it only looks like it.
+ *
+ * The mask is a FIXED length. Deriving it from the value would leak how long
+ * the secret is, which is the sort of detail masking exists to withhold.
+ */
+export const useTspReveal = (maskLength = 24) => {
+  const revealed = ref(false)
+  const toggle = () => { revealed.value = !revealed.value }
+  const mask = '•'.repeat(maskLength)
+
+  return { revealed, toggle, mask }
+}