@thespielplatz/tsp-tools-theme 0.2.1 → 0.3.0

package/components/TspSidebarFooter.vue

@@ -1,60 +1,355 @@
 <!--
-  The sidebar bottom block, in canonical order:
-    User label → #user → #logout → divider → theme toggle → GitHub + version.
+  The sidebar bottom block, in the order spec 03 fixes:
 
-  App-specific identity (the user link, the logout target) come in as slots; the
-  GitHub/version come in as props. The theme toggle is built in.
+    User label → user → settings → logout
+    ───────────
+    [theme ……… DE|EN] → [github · support · tip jar ……… version] → “A tool of…”
+
+  The divider separates ACCOUNT from PREFERENCES: above it is who you are, your
+  settings and leaving; below it is how the app looks and speaks, plus the meta
+  links. All four rows share one left edge and one 32px height. Before 0.3.0 the
+  language toggle was positioned by each app (`class="mt-1 ml-3"`) and the theme
+  toggle row was text-xs/px-1 against TspFooterRow's text-sm/px-3 — spec 01
+  shipped that mismatch knowingly and left it open; this closes it.
+
+  PROPS, NOT SLOTS, for the rows every app has. A slot invites each app to
+  re-style its own copy, which is the drift TspFooterRow was created to stop.
+  `#user` survives only for apps that need more than a name.
+
+  OPEN SOURCE IS DERIVED FROM `githubLink`. Fil's framing: "I just define in a
+  project if it's open source, and then there will be a GitHub link or not." So
+  the link is the consequence of the fact, and a separate `variant` prop would
+  be a second source of truth that can disagree with it.
+
+    githubLink set   → theme-toggle row, then a GitHub row whose version badge
+                       links to the release.
+    githubLink unset → one row: theme toggle with a PLAIN-TEXT version badge.
+                       `versionLink` is then a no-op, silently (a warning would
+                       scold someone for passing both and toggling githubLink
+                       per environment, which is reasonable).
+
+  The language row renders only when `locales` is passed — that is what makes it
+  absent for the services that are not bilingual.
 -->
 <template>
   <div>
     <p
-      v-if="$slots.user"
-      class="px-1 mb-1 text-[10px] uppercase tracking-wide text-dimmed"
+      v-if="user || $slots.user"
+      data-testid="tsp-user-label"
+      class="px-3 mb-1 text-[10px] uppercase tracking-wide text-muted"
     >
-      User
+      {{ userLabel }}
     </p>
-    <slot name="user" />
-    <slot name="logout" />
 
-    <TspThemeToggle class="w-full mt-2 pt-2.5 pb-1.5 border-t border-default" />
+    <slot name="user">
+      <!-- A LINK when `userTo` is given — the user page is a real destination,
+           and the row then goes amber on it like any other active row. Without
+           it the row is plain text. The icon inherits the row colour either
+           way: the original complaint was an amber icon on a row that was
+           neither selected nor clickable. -->
+      <TspFooterRow
+        v-if="user && userTo"
+        data-footer-row="user"
+        data-testid="tsp-user"
+        :to="userTo"
+        :icon="userIcon"
+      >
+        <span class="truncate">{{ user }}</span>
+      </TspFooterRow>
+      <p
+        v-else-if="user"
+        data-footer-row="user"
+        data-testid="tsp-user"
+        :class="[ROW, 'text-muted']"
+      >
+        <UIcon
+          v-if="userIcon"
+          :name="userIcon"
+          class="text-lg shrink-0"
+        />
+        <span class="truncate">{{ user }}</span>
+      </p>
+    </slot>
 
-    <div
-      v-if="githubLink || version"
-      class="flex items-center gap-1.5 px-1 pt-1.5 text-xs text-muted"
+    <TspFooterRow
+      v-if="settingsTo"
+      data-footer-row="settings"
+      :to="settingsTo"
+      icon="i-tabler-settings"
     >
-      <a
-        v-if="githubLink"
-        :href="githubLink"
-        target="_blank"
-        rel="noopener noreferrer"
-        class="flex items-center gap-1 hover:text-highlighted"
+      {{ settingsLabel }}
+    </TspFooterRow>
+
+    <!-- The slot is kept as an escape hatch, exactly like #user. Removing it
+         was a SILENT break: Vue discards content for a slot that no longer
+         exists, so every consumer still passing #logout would have lost its
+         logout control with no error, no warning and no build failure. -->
+    <slot name="logout">
+      <TspFooterRow
+        v-if="logoutTo || logoutHref"
+        data-footer-row="logout"
+        :to="logoutTo"
+        :href="logoutHref"
+        icon="i-tabler-logout"
       >
-        <UIcon name="i-tabler-brand-github" />
-        GitHub
-      </a>
-      <a
-        v-if="versionLink"
-        :href="versionLink"
-        target="_blank"
-        rel="noopener noreferrer"
-        class="ml-auto rounded-full border border-default px-2 py-0.5 hover:text-highlighted hover:border-accented"
+        {{ logoutLabel }}
+      </TspFooterRow>
+    </slot>
+
+    <div class="mt-2 pt-2 border-t border-default">
+      <!-- Language sits BELOW the divider with the theme toggle: both are
+           display preferences, while everything above the line is the account
+           (who you are, your settings, leaving). -->
+      <!-- Preferences row: theme on the left with its label, language on the
+           right. The old "Sprache" text is gone — a DE/EN segmented control
+           says what it is, so the label was carrying nothing, and the space it
+           freed is what lets the theme toggle keep ITS label instead of being
+           an unexplained sun. The row itself has no padding: the toggle brings
+           its own px-3, so the icon still lands on the 12px column. -->
+      <div
+        data-footer-row="preferences"
+        class="flex items-center h-8"
       >
-        {{ version }}
-      </a>
-      <span
-        v-else-if="version"
-        class="ml-auto rounded-full border border-default px-2 py-0.5"
+        <TspThemeToggle
+          :label-to-light="labelToLight"
+          :label-to-dark="labelToDark"
+          :aria-label-to-light="ariaLabelToLight"
+          :aria-label-to-dark="ariaLabelToDark"
+        />
+        <TspLanguageToggle
+          v-if="locales?.length"
+          class="ml-auto mr-3"
+          :model-value="modelValue"
+          :locales="locales"
+          :group-label="languageGroupLabel"
+          :labels="languageLabels"
+          @update:model-value="emit('update:modelValue', $event)"
+        />
+      </div>
+
+      <div
+        data-testid="tsp-meta-row"
+        class="flex items-center gap-1 h-8 px-2 text-muted"
       >
-        {{ version }}
-      </span>
+        <a
+          v-if="githubLink"
+          data-testid="tsp-github-link"
+          :href="githubLink"
+          :aria-label="githubLabel"
+          :title="githubLabel"
+          target="_blank"
+          rel="noopener noreferrer"
+          :class="ICON"
+        >
+          <UIcon
+            name="i-tabler-brand-github"
+            class="text-lg block"
+          />
+        </a>
+        <a
+          v-if="supportEmail"
+          data-testid="tsp-support-link"
+          :href="supportHref"
+          :aria-label="supportLabel"
+          :title="supportLabel"
+          :class="ICON"
+        >
+          <UIcon
+            name="i-tabler-mail"
+            class="text-lg block"
+          />
+        </a>
+        <a
+          v-if="tipJar"
+          data-testid="tsp-tip-jar-link"
+          :href="tipJarLink"
+          :aria-label="tipJarLabel"
+          :title="tipJarLabel"
+          target="_blank"
+          rel="noopener noreferrer"
+          :class="ICON"
+        >
+          <UIcon
+            name="i-tabler-coin"
+            class="text-lg block"
+          />
+        </a>
+
+        <TspVersionBadge
+          v-if="version"
+          class="ml-auto"
+          :version="version"
+          :href="githubLink ? versionLink : undefined"
+          :unread="versionUnread"
+        />
+      </div>
+
+      <TspToolOf
+        v-if="toolOf"
+        class="px-3 pt-2 pb-0.5"
+        :label="toolOfLabel"
+        :name="toolOfName"
+        :link="toolOfLink"
+      />
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
-defineProps<{
+// One row shape for every row in this block: 32px tall, 12px left edge, 14px
+// text. Fixed height rather than vertical padding, because the language row
+// holds a control and would otherwise come out taller than its neighbours.
+const ROW = 'flex items-center gap-2.5 h-8 px-3 rounded-md text-sm font-normal'
+// Icon control in the meta row. p-1 on top of the row's px-2 puts the glyph on
+// the same 12px column as the icons in the rows above.
+const ICON = 'flex items-center p-1 rounded-md hover:text-highlighted hover:bg-default'
+
+const props = withDefaults(defineProps<{
+  /** The username. Plain text, no icon. Use #user only if you need more. */
+  user?: string
+  /** Accessible name for the user row. */
+  userLabel?: string
+  /** Icon for the user row. Pass `undefined` for a bare name. */
+  userIcon?: string
+  /** Route to the user page. Given, the row becomes a link and can go active. */
+  userTo?: string
+
+  /** Route to the settings page. Omit to drop the row. */
+
+  settingsTo?: string
+  /** Visible text of the settings row. */
+  settingsLabel?: string
+
+  /** Internal logout route. Use this or `logoutHref`, not both. */
+
+  logoutTo?: string
+  /** External logout URL — the usual case with a hosted identity provider. */
+  logoutHref?: string
+  /** Visible text of the logout row. */
+  logoutLabel?: string
+
+  /** Active locale (v-model). The language toggle renders only with `locales`. */
+  modelValue?: string
+  /** Locale codes, e.g. `['de', 'en']`. The language row appears only with this — not every
+   * service is translated.
+   */
+  locales?: string[]
+  /** Accessible name for the locale group. There is no visible label. */
+  languageGroupLabel?: string
+  /** Accessible names per code, e.g. `{ de: 'Deutsch' }`. The button itself shows the code. */
+  languageLabels?: Record<string, string>
+
+  /** Presence of this is what makes the project open source. */
   githubLink?: string
+  /** Accessible name for the GitHub icon. */
+  githubLabel?: string
+  /** Support address. One platform mailbox, so it has a default. */
+  supportEmail?: string
+  /** Accessible name for the support icon. */
+  supportLabel?: string
+  /** Subject line. Defaults to one naming this app, so support can tell which. */
+  supportSubject?: string
+  /** First line of the body. Defaults to app + version, for the same reason. */
+  supportBody?: string
+  /** This app's name, used in the support subject/body and nothing else. */
+  appName?: string
+  /** The tip jar icon. Same destination for every service, so only a boolean. */
+  tipJar?: boolean
+  /** Accessible name for the tip-jar icon. */
+  tipJarLabel?: string
+  /** Where it goes. One destination for the whole platform, so services do not set this. */
+  tipJarLink?: string
+  /** Version string for the badge, e.g. `v0.3.0`. Omit to drop the badge. */
   version?: string
+  /** Release link for the badge. Ignored without `githubLink`. */
   versionLink?: string
-}>()
+  /** Mark the version badge as having unseen release notes. */
+  versionUnread?: boolean
+
+  /** The “A tool of tsp.tools” line. Off by default; only some services carry it. */
+  toolOf?: boolean
+  /** Leading words of the attribution. Left undefined so TspToolOf owns the default. */
+  toolOfLabel?: string
+  /** The platform name in it. Same reason. */
+  toolOfName?: string
+  /** Where that name points. Same reason. */
+  toolOfLink?: string
+
+  /** Theme-toggle text while dark — it names the DESTINATION. */
+
+  labelToLight?: string
+  /** Theme-toggle text while light. */
+  labelToDark?: string
+  /** Its accessible name while dark. */
+  ariaLabelToLight?: string
+  /** Its accessible name while light. */
+  ariaLabelToDark?: string
+}>(), {
+  user: undefined,
+  userLabel: 'User',
+  userIcon: 'i-tabler-user-circle',
+  userTo: undefined,
+  settingsTo: undefined,
+  settingsLabel: 'Settings',
+  logoutTo: undefined,
+  logoutHref: undefined,
+  logoutLabel: 'Logout',
+  modelValue: undefined,
+  locales: undefined,
+  languageGroupLabel: 'Language',
+  languageLabels: undefined,
+  githubLink: undefined,
+  githubLabel: 'GitHub',
+  // The platform mailbox, not a per-service one — so it is a default rather
+  // than something eight apps each retype.
+  supportEmail: 'support@tsp.tools',
+  supportLabel: 'Support',
+  supportSubject: undefined,
+  supportBody: undefined,
+  appName: undefined,
+  // Opt-in, not on by default: switching it on would put a money link into
+  // every consuming app on upgrade, which is not something a version bump
+  // should decide.
+  tipJar: false,
+  tipJarLabel: 'Tip jar',
+  tipJarLink: 'https://thespielplatz.com/tip-jar',
+  version: undefined,
+  versionLink: undefined,
+  versionUnread: false,
+  toolOf: false,
+  // Left undefined so TspToolOf's own defaults apply — the same pattern as the
+  // theme-toggle labels below. Restating them here would be a second source of
+  // truth for one string set, which is what this component's header warns
+  // against for githubLink.
+  toolOfLabel: undefined,
+  toolOfName: undefined,
+  toolOfLink: undefined,
+  labelToLight: undefined,
+  labelToDark: undefined,
+  ariaLabelToLight: undefined,
+  ariaLabelToDark: undefined,
+})
+
+const emit = defineEmits<{ 'update:modelValue': [code: string] }>()
+
+// A support mail should arrive already saying which service and which version
+// it came from — otherwise that is the first round-trip of every support
+// thread. Subject and body are overridable, but never empty.
+// A bare mailbox only. The address used to be interpolated raw while the
+// subject and body were encoded — so a value carrying `?`, `&` or a comma could
+// add recipients or headers to the mail the user is about to send. It is a
+// prop, and a prop is exactly what a service wires to config.
+const MAILBOX = /^[^\s@,?&]+@[^\s@,?&]+\.[^\s@,?&]+$/
+
+const supportHref = computed(() => {
+  if (!props.supportEmail || !MAILBOX.test(props.supportEmail)) return undefined
+  const app = props.appName ?? 'tsp.tools'
+  const subject = props.supportSubject ?? `${app} — Support`
+  const body = props.supportBody
+    ?? `\n\n—\n${app}${props.version ? ` ${props.version}` : ''}`
+  // encodeURIComponent, not URLSearchParams: the latter encodes spaces as "+",
+  // which mail clients show literally in the subject line.
+  const query = `subject=${encodeURIComponent(subject)}&body=${encodeURIComponent(body)}`
+  return `mailto:${props.supportEmail}?${query}`
+})
 </script>

package/components/TspSiteFooter.vue

@@ -1,40 +1,71 @@
 <!--
-  Marketing/public site footer (ADR 008, finding 2). Frame only: top border,
-  site-width column, brand block over a wrapping link row. The app supplies the
-  content; the legal routes and their labels stay with the app.
+  Marketing/public site footer (ADR 008, finding 2). Frame only: a top border
+  and one centred row of links, with the platform attribution under it.
 
-    #brand   — logo + wordmark (+ tagline)
-    #links   — inline links, muted
-    #actions — pushed to the right on ≥sm, e.g. a language toggle
+    #brand   — optional mark/wordmark above the row
+    #links   — inline links, muted. Give them icons; the row is compact and an
+               icon carries a short label better than a word alone at this size.
+    #actions — trailing items on the same row, e.g. <TspVersionBadge>
+
+  COMPACT AND CENTRED. It used to be a tall left-aligned block with the brand
+  stacked over a link row — a lot of vertical space at the end of a page that
+  has already said everything. One centred row reads as a footer rather than as
+  a final section, and matches what stash runs in production.
 
   The link row renders only when #links or #actions is filled.
+
+  `tool-of` adds the “A tool of tsp.tools” line below it — the same component
+  the sidebar footer uses, so the two attributions cannot drift.
 -->
 <template>
-  <footer class="border-t border-muted pt-9 pb-12">
+  <footer class="border-t border-muted pt-6 pb-8">
     <TspContainer
       width="site"
       :padded="false"
     >
       <div
         v-if="$slots.brand"
-        class="flex items-center gap-3"
+        class="flex items-center justify-center gap-3 mb-5"
       >
         <slot name="brand" />
       </div>
 
       <div
         v-if="$slots.links || $slots.actions"
-        class="mt-6 flex flex-wrap items-center gap-x-6 gap-y-2.5 text-sm text-muted"
+        class="flex flex-wrap items-center justify-center gap-x-6 gap-y-3 text-sm text-muted"
       >
         <slot name="links" />
-
-        <div
-          v-if="$slots.actions"
-          class="sm:ml-auto"
-        >
-          <slot name="actions" />
-        </div>
+        <slot name="actions" />
       </div>
+
+      <TspToolOf
+        v-if="toolOf"
+        class="mt-4 text-center"
+        :label="toolOfLabel"
+        :name="toolOfName"
+        :link="toolOfLink"
+      />
     </TspContainer>
   </footer>
 </template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  /** The “A tool of tsp.tools” line. Off by default; only some services carry it. */
+  toolOf?: boolean
+  /** Leading words of the attribution. Left undefined so TspToolOf owns the default. */
+  toolOfLabel?: string
+  /** The platform name in it. Same reason. */
+  toolOfName?: string
+  /** Where that name points. Same reason. */
+  toolOfLink?: string
+}>(), {
+  toolOf: false,
+  // Left undefined so TspToolOf's own defaults apply. Restating them here would
+  // make this a second source of truth for one string set, which is how the two
+  // footers' attributions would quietly drift apart.
+  toolOfLabel: undefined,
+  toolOfName: undefined,
+  toolOfLink: undefined,
+})
+</script>

package/components/TspSiteHeader.vue

@@ -10,13 +10,25 @@
     #actions — right-hand cluster, e.g. <TspThemeToggle> + a CTA
 
   Pass `:sticky="false"` for a header that scrolls away.
+
+  `bare` drops the bar entirely — no border, no background, not sticky — leaving
+  just the controls floating over the page. That is what a LANDING page wants:
+  the brand is already the hero, so repeating it in a header bar says the same
+  thing twice and puts a line across the top of an otherwise open page. A
+  logged-out *content* page still wants the real bar, because there the brand is
+  the only way back.
 -->
 <template>
-  <header :class="['border-b border-muted bg-default/90 backdrop-blur', sticky ? 'sticky top-0 z-50' : '']">
+  <header
+    :class="[
+      bare ? '' : 'border-b border-muted bg-default/90 backdrop-blur',
+      sticky && !bare ? 'sticky top-0 z-50' : '',
+    ]"
+  >
     <TspContainer
       width="site"
       :padded="false"
-      class="flex h-18 items-center"
+      :class="['flex items-center', bare ? 'h-16' : 'h-18']"
     >
       <slot name="brand" />
 
@@ -39,8 +51,12 @@
 
 <script setup lang="ts">
 withDefaults(defineProps<{
+  /** Keep the bar at the top of the viewport. Ignored when `bare`. */
   sticky?: boolean
+  /** No bar: no border, no background, not sticky. For landing pages. */
+  bare?: boolean
 }>(), {
   sticky: true,
+  bare: false,
 })
 </script>

package/components/TspThemeToggle.vue

@@ -1,9 +1,17 @@
 <!--
-  Light/dark toggle. Flips the remembered preference (useTspColorMode); the
+  Light/dark toggle. Shares the 32px row shape of everything else in the
+  sidebar footer (spec 03 — it used to be text-xs/px-1 against the rows'
+  text-sm/px-3, which is the mismatch spec 01 shipped knowingly).
+
+  Flips the remembered preference (useTspColorMode); the
   colour-mode plugin applies it. Default content is an icon + label; override via
   the default slot (receives `{ isDark, label }`). The button is unstyled-ish so it
   fits the sidebar footer or a top bar — pass classes to taste.
 
+  `icon-only` drops the label for tight places — the sidebar's meta row, and the
+  landing-page header, which wants just a sun/moon. The aria-label stays either
+  way: an icon-only control is only as good as its label.
+
   All four strings are props so a bilingual site can pass its own (ADR 008,
   finding 4). Naming is by *destination*: `…ToLight` is what the button shows and
   announces while dark, because pressing it switches to light.
@@ -18,14 +26,17 @@
     type="button"
     data-testid="tsp-theme-toggle"
     :aria-label="isDark ? ariaLabelToLight : ariaLabelToDark"
-    class="flex items-center gap-2 px-1 py-1.5 rounded-md text-xs text-muted hover:text-highlighted hover:bg-default"
+    :class="iconOnly
+      ? 'flex items-center p-1 rounded-md text-muted hover:text-highlighted hover:bg-default'
+      : 'flex items-center gap-2.5 h-8 px-3 rounded-md text-sm text-muted hover:text-highlighted hover:bg-default'"
     @click="toggle"
   >
     <UIcon
       :name="isDark ? 'i-tabler-sun' : 'i-tabler-moon'"
-      class="text-base"
+      :class="iconOnly ? 'text-lg block' : 'text-base'"
     />
     <slot
+      v-if="!iconOnly"
       :is-dark="isDark"
       :label="label"
     >{{ label }}</slot>
@@ -42,11 +53,19 @@ const props = withDefaults(defineProps<{
   ariaLabelToLight?: string
   /** aria-label while light. */
   ariaLabelToDark?: string
+  /** Drop the visible label and render a compact icon button. */
+  iconOnly?: boolean
 }>(), {
-  labelToLight: 'Light mode',
-  labelToDark: 'Dark mode',
+  // Just "Light" / "Dark": the word "mode" earns nothing next to a sun icon,
+  // and the label shares a 224px row with the language control — at "Light
+  // mode" the two sat flush with a pixel to spare, and a longer translation
+  // overflowed. The ARIA labels keep the full phrasing, where the extra words
+  // do work.
+  labelToLight: 'Light',
+  labelToDark: 'Dark',
   ariaLabelToLight: 'Switch to light mode',
   ariaLabelToDark: 'Switch to dark mode',
+  iconOnly: false,
 })
 
 const { pref, toggle } = useTspColorMode()

package/components/TspToolOf.vue

@@ -0,0 +1,42 @@
+<!--
+  “A tool of tsp.tools” — the platform attribution line.
+
+  One component because it appears in BOTH footers: the sidebar's and the
+  landing page's (spec 03). Writing it twice is how the two drift apart.
+
+  Only the leading words translate (`label`, German "Ein Tool von"). The domain
+  never does, and the link is always ours — so an app never hand-rolls markup to
+  translate a sentence that contains a link, which is the thing this layer
+  exists to prevent. This works because DE and EN both put the domain last; a
+  language that needs it mid-sentence would need a different shape.
+
+  Not a flex row: it is a sentence and has to stay one inline flow.
+-->
+<template>
+  <p
+    data-testid="tsp-tool-of"
+    class="text-xs text-dimmed"
+  >
+    {{ label }}&nbsp;<a
+      :href="link"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="underline underline-offset-2 hover:text-highlighted"
+    >{{ name }}</a>
+  </p>
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  /** The leading words. */
+  label?: string
+  /** The platform, not the service. A service never names itself here. */
+  name?: string
+  /** Where the name points. */
+  link?: string
+}>(), {
+  label: 'A tool of',
+  name: 'tsp.tools',
+  link: 'https://tsp.tools',
+})
+</script>