@thespielplatz/tsp-tools-theme 0.1.2 → 0.2.0

package/README.md

@@ -147,14 +147,55 @@ for the themed area.
 | `TspThemeProvider` | Scoped wrapper — marks a sub-area as themed (`.tsp-theme`). |
 | `TspSidebar` | App-shell sidebar frame; slots `#brand` `#nav` `#footer`. |
 | `TspSidebarFooter` | User → Logout → divider → theme toggle → GitHub + version. |
+| `TspSiteHeader` | Public/marketing header; slots `#brand` `#nav` `#actions`, prop `sticky`. |
+| `TspSiteFooter` | Public/marketing footer; slots `#brand` `#links` `#actions`. |
 | `TspThemeToggle` | Sun/moon light–dark toggle (uses `useTspColorMode`). |
 | `TspNavItem` | Sidebar nav link (muted → filled-amber when active). |
 | `TspWordmark` | Space Grotesk + amber brand wordmark. |
-| `TspContainer` | Centered content column (`max-w-4xl`, `px-6 sm:px-10`, `pt-10 pb-16`). |
+| `TspContainer` | Centered content column; props `width` (`app` \| `site`) and `padded`. |
 
 App-specific content (branding, nav lists, user identity, GitHub/version values) is injected
 via slots/props — none of it lives in the layer.
 
+### App shell vs site shell
+
+`TspSidebar` + `TspSidebarFooter` are the **logged-in** shell. For a public/marketing surface
+use `TspSiteHeader` + `TspSiteFooter` with the wide container:
+
+```vue
+<TspSiteHeader>
+  <template #brand><NuxtLink to="/"><TspWordmark>tsp<span class="text-primary">.</span>tools</TspWordmark></NuxtLink></template>
+  <template #nav><a href="#tools">Tools</a></template>
+  <template #actions><TspThemeToggle /></template>
+</TspSiteHeader>
+
+<TspContainer width="site"><NuxtPage /></TspContainer>
+
+<TspSiteFooter>
+  <template #brand><TspWordmark>tsp<span class="text-primary">.</span>tools</TspWordmark></template>
+  <template #links><NuxtLink to="/imprint">Imprint</NuxtLink></template>
+</TspSiteFooter>
+```
+
+`TspContainer` defaults to `width="app"` (`max-w-4xl`, `px-6 sm:px-10`) — the app/admin measure.
+`width="site"` is `max-w-[1240px]`, `px-6 md:px-10`, the marketing measure. Both add `pt-10 pb-16`
+unless you pass `:padded="false"` (which is what the header/footer frames do internally).
+
+### Localising the theme toggle
+
+`TspThemeToggle` takes all four strings as props, named by destination — `…ToLight` is what the
+button shows and announces while dark:
+
+```vue
+<TspThemeToggle
+  :label-to-light="t('theme.light')"      :label-to-dark="t('theme.dark')"
+  :aria-label-to-light="t('theme.toLight')" :aria-label-to-dark="t('theme.toDark')"
+/>
+```
+
+The defaults are English. The default slot receives `{ isDark, label }` if you want different
+markup (an icon-only square button, say) while keeping the mechanism.
+
 ---
 
 ## Why `primary` isn't set in `app.config`
@@ -203,6 +244,21 @@ npm run build:playground
 The `playground/` (global) and `scoped/` demos are direct-child layers that `extends: ['..']`.
 They are excluded from the published package (`files` allowlist).
 
+## Release
+
+The version bump and the git tag are **not** done by an npm script:
+
+1. Bump `package.json` `.version`, commit, and push to `main`.
+2. Publish a GitHub Release for that commit — GitHub creates the `vX.Y.Z` tag on publish.
+3. Ship the package:
+
+   ```bash
+   npm run release      # lint, then npm publish
+   ```
+
+`npm run release` deliberately only lints and publishes. It never bumps the version or tags,
+so it can't drift from the version that was already committed and tagged in steps 1–2.
+
 ## License
 
 MIT © TheSpielplatz

package/components/TspContainer.vue

@@ -1,9 +1,32 @@
 <!--
-  Centered content column (design-system.md → Layout): max-w-4xl with
-  px-6 sm:px-10 / pt-10 pb-16. The background stays full-bleed behind it.
+  Centered content column.
+
+  `width` picks the measure (ADR 008, finding 3):
+    app   — max-w-4xl, the logged-in app/admin measure (design-system.md → Layout). Default.
+    site  — 1240px, the marketing measure from the approved storefront mockup.
+
+  `padded` controls the vertical rhythm (pt-10 pb-16). It suits a page body, so it
+  is on by default; header/footer rows want none, so pass `:padded="false"`.
+  The background stays full-bleed behind the column either way.
 -->
 <template>
-  <div class="max-w-4xl mx-auto px-6 sm:px-10 pt-10 pb-16">
+  <div :class="classes">
     <slot />
   </div>
 </template>
+
+<script setup lang="ts">
+const props = withDefaults(defineProps<{
+  width?: 'app' | 'site'
+  padded?: boolean
+}>(), {
+  width: 'app',
+  padded: true,
+})
+
+const classes = computed(() => [
+  'mx-auto',
+  props.width === 'site' ? 'max-w-[1240px] px-6 md:px-10' : 'max-w-4xl px-6 sm:px-10',
+  props.padded ? 'pt-10 pb-16' : '',
+])
+</script>

package/components/TspSiteFooter.vue

@@ -0,0 +1,40 @@
+<!--
+  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.
+
+    #brand   — logo + wordmark (+ tagline)
+    #links   — inline links, muted
+    #actions — pushed to the right on ≥sm, e.g. a language toggle
+
+  The link row renders only when #links or #actions is filled.
+-->
+<template>
+  <footer class="border-t border-muted pt-9 pb-12">
+    <TspContainer
+      width="site"
+      :padded="false"
+    >
+      <div
+        v-if="$slots.brand"
+        class="flex items-center gap-3"
+      >
+        <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"
+      >
+        <slot name="links" />
+
+        <div
+          v-if="$slots.actions"
+          class="sm:ml-auto"
+        >
+          <slot name="actions" />
+        </div>
+      </div>
+    </TspContainer>
+  </footer>
+</template>

package/components/TspSiteHeader.vue

@@ -0,0 +1,46 @@
+<!--
+  Marketing/public site header (ADR 008, finding 2 — the counterpart to
+  TspSidebar, which only fits the logged-in shell). Frame only: sticky bar,
+  bottom border, translucent backdrop, site-width column. The app supplies the
+  content via slots; no branding, nav or copy lives here.
+
+    #brand   — wordmark / logo link (left)
+    #nav     — inline links; hidden below 900px, so pair it with your own
+               mobile disclosure if you need one
+    #actions — right-hand cluster, e.g. <TspThemeToggle> + a CTA
+
+  Pass `:sticky="false"` for a header that scrolls away.
+-->
+<template>
+  <header :class="['border-b border-muted bg-default/90 backdrop-blur', sticky ? 'sticky top-0 z-50' : '']">
+    <TspContainer
+      width="site"
+      :padded="false"
+      class="flex h-18 items-center"
+    >
+      <slot name="brand" />
+
+      <nav
+        v-if="$slots.nav"
+        class="ml-2 hidden gap-6 min-[900px]:flex"
+      >
+        <slot name="nav" />
+      </nav>
+
+      <div
+        v-if="$slots.actions"
+        class="ml-auto flex items-center gap-2.5"
+      >
+        <slot name="actions" />
+      </div>
+    </TspContainer>
+  </header>
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  sticky?: boolean
+}>(), {
+  sticky: true,
+})
+</script>

package/components/TspThemeToggle.vue

@@ -1,14 +1,23 @@
 <!--
   Light/dark toggle. Flips the remembered preference (useTspColorMode); the
   colour-mode plugin applies it. Default content is an icon + label; override via
-  the default slot (receives `{ isDark }`). The button is unstyled-ish so it fits
-  the sidebar footer or a top bar — pass classes to taste.
+  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.
+
+  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.
+
+    <TspThemeToggle
+      :label-to-light="t('theme.light')"
+      :aria-label-to-light="t('theme.toLight')"
+      … />
 -->
 <template>
   <button
     type="button"
     data-testid="tsp-theme-toggle"
-    :aria-label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
+    :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"
     @click="toggle"
   >
@@ -16,11 +25,31 @@
       :name="isDark ? 'i-tabler-sun' : 'i-tabler-moon'"
       class="text-base"
     />
-    <slot :is-dark="isDark">{{ isDark ? 'Light mode' : 'Dark mode' }}</slot>
+    <slot
+      :is-dark="isDark"
+      :label="label"
+    >{{ label }}</slot>
   </button>
 </template>
 
 <script setup lang="ts">
+const props = withDefaults(defineProps<{
+  /** Visible label while dark (pressing switches to light). */
+  labelToLight?: string
+  /** Visible label while light. */
+  labelToDark?: string
+  /** aria-label while dark. */
+  ariaLabelToLight?: string
+  /** aria-label while light. */
+  ariaLabelToDark?: string
+}>(), {
+  labelToLight: 'Light mode',
+  labelToDark: 'Dark mode',
+  ariaLabelToLight: 'Switch to light mode',
+  ariaLabelToDark: 'Switch to dark mode',
+})
+
 const { pref, toggle } = useTspColorMode()
 const isDark = computed(() => pref.value === 'dark')
+const label = computed(() => isDark.value ? props.labelToLight : props.labelToDark)
 </script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thespielplatz/tsp-tools-theme",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "tsp.tools design-system theme as a Nuxt layer (Nuxt UI v4 + Tailwind v4): amber-on-anthracite tokens (light + dark), Nunito/Space Grotesk fonts, per-area colour mode, and the shared app shell. Use globally via `extends`, or scoped to a sub-area.",
   "author": "inf0matics",
   "license": "MIT",
@@ -47,8 +47,8 @@
     "dev:scoped": "nuxi dev scoped",
     "build:playground": "nuxi build playground",
     "build:scoped": "nuxi build scoped",
-    "release": "npm run lint && changelogen --release && git push --follow-tags && npm publish",
-    "bump-patch": "npx changelogen@latest --release"
+    "typecheck": "nuxi typecheck playground && nuxi typecheck scoped",
+    "release": "npm run lint && npm run typecheck && npm publish"
   },
   "dependencies": {
     "@nuxt/ui": "^4.10.0"
@@ -65,7 +65,7 @@
   "devDependencies": {
     "@iconify-json/tabler": "^1.2.37",
     "@nuxt/eslint-config": "^1.16.0",
-    "changelogen": "^0.6.2",
+    "@types/node": "^26.1.2",
     "eslint": "^10.8.0",
     "nuxt": "^4.5.1",
     "vue-tsc": "3.3.8"

package/plugins/01.tspColorMode.ts

@@ -35,7 +35,13 @@ export default defineNuxtPlugin((nuxtApp) => {
   const apply = (path: string) => {
     const mode = modeForPath(path)
     colorMode.preference = mode
-    colorMode.value = mode
+    // colour-mode v4 types `value` as readonly, but still mutates it internally
+    // (it is a plain `reactive`, not a computed). We assign it deliberately: its
+    // client plugin derives `value` from `preference` only on the next tick, and
+    // its *server* plugin never derives it at all — so without this, `value`
+    // would fall back to colour-mode's own cookie during SSR and disagree with
+    // the route-derived mode in scoped setups.
+    ;(colorMode as { value: string }).value = mode
     if (import.meta.client) {
       const el = document.documentElement
       el.classList.remove('dark', 'light')