npm - @thespielplatz/tsp-tools-theme - Versions diffs - 0.2.1 → 0.3.1 - Mend

@thespielplatz/tsp-tools-theme 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/CHANGELOG.md +144 -0
package/README.md +148 -44
package/assets/css/theme.css +86 -6
package/components/TspBanner.vue +97 -0
package/components/TspBrandTile.vue +46 -0
package/components/TspCodeBlock.vue +68 -0
package/components/TspContainer.vue +10 -2
package/components/TspCopyButton.vue +40 -0
package/components/TspCopyField.vue +102 -0
package/components/TspFooterRow.vue +56 -0
package/components/TspLanguageToggle.vue +75 -0
package/components/TspNavBadge.vue +36 -0
package/components/TspNavGroup.vue +58 -0
package/components/TspNavItem.vue +68 -12
package/components/TspNavLabel.vue +56 -0
package/components/TspNavSection.vue +33 -0
package/components/TspNavSubItem.vue +35 -0
package/components/TspPageTabs.vue +46 -0
package/components/TspReleaseNotes.vue +143 -0
package/components/TspSectionCard.vue +52 -0
package/components/TspSidebar.vue +96 -3
package/components/TspSidebarFooter.vue +332 -37
package/components/TspSiteFooter.vue +47 -16
package/components/TspSiteHeader.vue +18 -2
package/components/TspThemeToggle.vue +24 -5
package/components/TspToolOf.vue +42 -0
package/components/TspTopBar.vue +69 -0
package/components/TspUserCard.vue +127 -0
package/components/TspVersionBadge.vue +49 -0
package/components/TspWordmark.vue +36 -4
package/composables/useTspCopy.ts +72 -0
package/composables/useTspNavDrawer.ts +14 -0
package/composables/useTspReveal.ts +18 -0
package/docs/api.md +394 -0
package/docs/design-system.md +297 -0
package/nuxt.config.ts +11 -0
package/package.json +24 -13
package/page-meta.d.ts +11 -0
package/plugins/01.tspColorMode.ts +12 -0

package/docs/design-system.md ADDED Viewed

@@ -0,0 +1,297 @@
+# tsp.tools Design System
+**This file is the source of truth for how tsp.tools services look.**
+It lives in the package that ships the design, not beside it. Values here are read from
+`assets/css/theme.css` and the components in `components/`; if the two ever disagree, the code is
+right and this file is a bug. The planning project's `architecture/design-system.md` is a pointer
+to this document, not a second copy — one description of the design, in the repo that implements
+it (ADR 008, ADR 017).
+The **playground is the reference**, never a mockup. `npm run dev` and look at it.
+Last reconciled with the code: 2026-09-22, theme `0.3.0`.
+**The complete prop, slot and emit surface is [`api.md`](api.md)** — generated from the
+components, checked in the gate, so it cannot drift. This file is the *why*; that one is the
+signature.
+---
+## Stack and installation
+Nuxt 4 · Nuxt UI 4 · Tailwind 4. The package is a Nuxt **layer**: it ships the tokens, the fonts,
+the colour-mode plugin and the shell components pre-configured. Extend it; do not restate tokens.
+```bash
+npm i -D @thespielplatz/tsp-tools-theme
+```
+```ts
+export default defineNuxtConfig({
+  extends: ['@thespielplatz/tsp-tools-theme'],
+  runtimeConfig: { public: { tspTheme: { apply: 'global' } } },
+})
+```
+### Two consumption modes
+| Mode | What is themed | Used by |
+|---|---|---|
+| `global` | the whole app; the plugin puts `.tsp-theme` on `<html>` | most services |
+| `scoped` | only routes under `pathPrefix`, wrapped in `<TspThemeProvider>`; the rest stays default Nuxt UI | piggybank (`/admin`) |
+**Anything that touches the scope class must be checked in both.** A change verified only
+globally is half verified — `playground/` is the global demo, `scoped/` the scoped one, and the
+E2E runs against both.
+`primary` is deliberately **not** set in `app.config`. `app.config` is global, so it would make
+every Nuxt UI component amber even in a scoped consumer's unthemed area. Brand theming comes from
+the `.tsp-theme` CSS scope, which resolves per element.
+---
+## Tokens
+### Brand
+`--color-tsp-amber-50 … 950`. The two that matter:
+| Token | Value | Use |
+|---|---|---|
+| `--color-tsp-amber-400` | `#fbad18` | the brand. Fills, and text on dark. |
+| `--color-tsp-amber-600` | `#f47920` | the same brand as **text on light**, where `#fbad18` fails contrast. |
+`--ui-primary` is amber-400 in both modes, because it paints **fills**, which are dark-text-on-
+amber either way. For amber **text** use `--tsp-text-brand` / `.tsp-text-brand`, which steps down
+to amber-600 on light. Getting this wrong is the single most repeated mistake in this codebase.
+### Surfaces — three rungs, and they are not interchangeable
+| Token | Dark | Light | Means |
+|---|---|---|---|
+| `--ui-bg` | `#212529` | `#f1f3f5` | the page |
+| `--ui-bg-muted` | `#2b3035` | `#f8f9fa` | **the shell** — sidebar, top bar |
+| `--ui-bg-elevated` | `#31373e` | `#ffffff` | **raised content** — cards, the user card |
+| `--ui-bg-accented` | `#404041` | `#dee2e6` | pressed/selected chrome |
+`muted` and `elevated` were once the same value, which left a card no surface of its own: it
+matched either the page or the sidebar, and it matched the sidebar in stash, gage and trips. They
+are separate rungs now. **The shell uses `muted`; content uses `elevated`.**
+### Text
+| Token | Dark | Light |
+|---|---|---|
+| `--ui-text-highlighted` | `#ffffff` | `#16191c` |
+| `--ui-text` | `#f0f0f0` | `#212529` |
+| `--ui-text-toned` | `#ced4da` | `#343a40` |
+| `--ui-text-muted` | `#adb5bd` | `#6d6e70` |
+| `--ui-text-dimmed` | `#6d6e70` | `#9ca3af` |
+### Borders
+`--ui-border` `#404041` / `#dee2e6` · `--ui-border-muted` `#343a40` / `#e9ecef` ·
+`--ui-border-accented` `#404041` / `#ced4da`.
+### Radius
+`--ui-radius` is **`0.25rem`**. Nuxt UI derives its whole scale from it:
+| Class | Multiple | Px | Used for |
+|---|---|---|---|
+| `rounded-sm` | 1× | 4 | inner chips |
+| `rounded-md` | 1.5× | 6 | rows, buttons, inputs, toggles |
+| `rounded-lg` | 2× | 8 | Nuxt UI's own default |
+| `rounded-xl` | 3× | 12 | **cards** |
+**The 12px card is a rule each app applies, not a layer default.** `UCard` hardcodes
+`rounded-lg`, so a plain card is 8px — write `rounded-xl` on cards you want at 12px. The layer
+does not override `ui.card.slots.root`, for the same reason it does not set `primary`: it is
+global and would reach a scoped consumer's unthemed area. There is no `TspCard`.
+> Nuxt UI runs **tailwind-merge** over the `class` prop, so `rounded-xl` *replaces*
+> `rounded-lg` rather than sitting beside it. Do not select on the default class in tests.
+### Fonts
+Nunito everywhere; Space Grotesk for the wordmark only (`.tsp-wordmark` / `<TspWordmark>`).
+Both from Google via `@nuxt/fonts`, which ships with Nuxt UI.
+### Icons
+Tabler, `i-tabler-*`. Install `@iconify-json/tabler` for offline resolution. **One icon family
+across the platform** — do not mix in a second set.
+### Utilities the layer adds
+| Class | What |
+|---|---|
+| `.tsp-theme` | the scope class; everything above resolves inside it |
+| `.tsp-text-brand` | mode-correct amber **text** |
+| `.tsp-border-brand` | mode-correct amber **left border** |
+| `.tsp-scroll-quiet` | scrolls, no visible scrollbar track |
+| `.tsp-wordmark` | Space Grotesk |
+`.tsp-text-brand` is written **unlayered** so it beats Tailwind's `text-*` utilities without
+`!important`.
+---
+## Layout
+`<TspContainer>` centres content. `width="app"` (default) is `max-w-6xl` (1152px), `px-6 sm:px-10`;
+`width="site"` is `max-w-[1240px]`, `px-6 md:px-10`. Both add `pt-10 pb-16` unless
+`:padded="false"`. The background stays full-bleed; only the column is constrained.
+**Components never cap the page width.** A layer component that puts a `max-w-*` on its own root
+overrides the container from the inside, and the app cannot undo it without fighting
+`tailwind-merge`. Width is the container's job; a service that wants a block narrower wraps it.
+The app measure is **not** a reading measure — it is sized for the tables, card grids and settings
+panels an app page is actually made of. Cap prose where the prose is (`max-w-2xl` on the
+paragraph), not by narrowing the whole page around it.
+**The scrollbar gutter is always reserved** (`html.tsp-theme, html:has(.tsp-theme)`). The column
+is centred, so without it the whole page slides sideways by half a scrollbar the moment a route
+is tall enough to scroll. Browsers with overlay scrollbars are unaffected, and a consumer's
+unthemed public pages are deliberately not touched.
+**Responsive.** `sm` (640px) is the shell's breakpoint. At and above it the sidebar is a column,
+sticky at viewport height. Below it the sidebar becomes an off-canvas drawer and `<TspTopBar>`
+appears.
+---
+## Components
+All auto-imported. App-specific content arrives as **props**, not slots, for the rows every app
+has — a slot invites each app to restyle its copy, which is the drift the layer exists to stop.
+### The logged-in shell
+| Component | Purpose |
+|---|---|
+| `TspSidebar` | The frame. Slots `#brand` `#nav` `#footer`. Sticky on desktop, drawer below `sm`. |
+| `TspTopBar` | Mobile only: burger (left) · brand · page title. |
+| `TspSidebarFooter` | User → Settings → Logout → divider → theme + language → meta icons + version → attribution. |
+| `TspFooterRow` | One footer row; `to` / `href` / neither (button). |
+| `TspNavItem` | Nav row. White at rest, amber when active. `to` or `href`, optional `badge`. |
+| `TspNavGroup` | A nav row with always-visible children on a hairline spine. |
+| `TspNavSubItem` | A child row — muted, own icon. |
+| `TspNavSection` | A rule, optionally labelled. |
+| `TspNavBadge` | Outline pill; `tone` `primary` \| `neutral`. |
+| `TspNavLabel` | Truncates a label, reveals it in full on hover. Used by the rows above. |
+| `TspVersionBadge` | Version pill with a tag icon. A link only with `href`; `unread` marks unseen notes. |
+| `TspLanguageToggle` | DE/EN segmented control. |
+| `TspThemeToggle` | Light/dark. `icon-only` for tight places. |
+| `TspToolOf` | “A tool of tsp.tools”. Shared by both footers. |
+### The public shell
+| Component | Purpose |
+|---|---|
+| `TspSiteHeader` | Slots `#brand` `#nav` `#actions`; `sticky`, and `bare` for a landing page (no bar). |
+| `TspSiteFooter` | Compact centred link row; `tool-of` adds the attribution. |
+### Content
+| Component | Purpose |
+|---|---|
+| `TspContainer` | The measure. |
+| `TspSectionCard` | Icon + title over content, on `bg-elevated`. |
+| `TspPageTabs` | Area tabs as **routes**, so the back button works. |
+| `TspCopyField` | Read-only value + copy; `secret` masks behind a reveal. |
+| `TspCopyButton` | Copy with a tick confirmation. |
+| `TspCodeBlock` | Config to copy. Separate shown and copied values. |
+| `TspUserCard` | Account card: name, masked id, manage link. |
+| `TspBanner` | Dismissible strip. Emits `dismiss`; remembering it is the app's job. |
+| `TspReleaseNotes` | Release notes. Props mirror the `tsp-release` skill's `RELEASES` shape. |
+### Brand
+| Component | Purpose |
+|---|---|
+| `TspWordmark` | `<TspWordmark name="trips" />` → white `trips` + amber dot. No slot. |
+| `TspBrandTile` | The frame around a mark: `sidebar` (24px) or `hero` (64/96px). Paints no fill. |
+| `TspThemeProvider` | Scoped mode: marks a sub-tree as themed. |
+### Composables
+All four are auto-imported; signatures and return shapes in [`api.md`](api.md).
+| Composable | For |
+|---|---|
+| `useTspColorMode()` | the themed area's own light/dark preference, in a cookie so SSR can read it |
+| `useTspNavDrawer()` | the mobile drawer's shared open state (`useState`, not a module ref, which would leak across requests on the server) |
+| `useTspCopy()` | copy + a moment of confirmation, with the fallback for a non-secure context (plain HTTP on a LAN address — how a service gets tested on a phone) |
+| `useTspReveal()` | show/hide a secret and the fixed-length placeholder to render instead of it |
+---
+## Rules
+**The wordmark is the app name, lowercase, terminated by an amber dot.** `trips.` `gage.`
+`stash.` The component owns the dot; there is no slot. `tsp.tools` is the *domain of the tool
+set*, not a tool's name, so it is never a wordmark subject.
+**Amber fills mean exactly one thing: primary buttons.** Nothing in the sidebar carries an amber
+fill at rest — not the active nav item, not a role badge, not the language toggle. The E2E sweeps
+for it on every run. The brand tile is the one deliberate exception, and it is SVG artwork rather
+than a CSS background.
+**The nav reads in three tones:** top-level rows white, children muted, the current route amber —
+at either level.
+**No cards inside cards.** A bordered, filled surface does not contain another. Use spacing, a
+rule, or a heading.
+**Every visible string is a prop with an English default.** No component hardcodes copy. Where a
+sentence contains a link, only the leading words are translatable and the component owns the
+link — an app must never hand-roll markup to translate a sentence.
+**Masking is real, not cosmetic.** A hidden secret is *not rendered*. Covering it with CSS leaves
+it in the page source, copyable and readable by anything walking the DOM.
+**Open source is derived from `github-link`**, not a separate flag: the link is the consequence
+of the fact, and a second source of truth could disagree with the first.
+**Area tabs** are for one area's own views; a **nav group** is for a service with nested areas.
+Both use `.tsp-text-brand` when active.
+---
+## Gates
+| Command | Covers |
+|---|---|
+| `npm run lint` | eslint |
+| `npm run docs:api:check` | `docs/api.md` still matches the components |
+| `npm run typecheck` | both demo apps (`nuxi typecheck`, i.e. vue-tsc — `tsc --noEmit` cannot resolve SFCs) |
+| `npm run test:icons` | boots both built apps and fails on one `failed to load icon` |
+| `npm run test:e2e` | Playwright, both consumption modes |
+| `npm test` | icons + e2e |
+| `npm run gate` | all of the above, in the order CI runs them |
+`.github/workflows/ci.yml` runs the gate on every push and pull request, building both demo apps
+once instead of the four times the scripts would do back to back. A version tag additionally runs
+`release.yml`, which re-runs the gate on a clean checkout and publishes to npm with provenance.
+**A green pipeline does not prove icons render.** Icons resolve at runtime, per request, so lint,
+typecheck and build all pass with every glyph missing. `test:icons` is part of the gate, not
+optional (ADR 008).
+The same trap has bitten twice more: `resolveComponent()` in a template expression renders a
+literal `<NuxtLink>` element with the build still green, and a Tailwind class collapse only shows
+in the browser. **Measure the rendered page**, which is what the E2E does.
+---
+## Decisions
+In the planning project's `decisions/`:
+- **ADR 008** — why this is a layer; the scoped/global mechanism; the icon trap
+- **ADR 017** — one shell for every service; the layer is the source
+- **ADR 018** (+ its 2026-09-21 and 2026-09-22 amendments) — the quiet shell, what `0.3.0`
+  revised, and the content measure

package/nuxt.config.ts CHANGED Viewed

@@ -9,6 +9,17 @@ const layerDir = dirname(fileURLToPath(import.meta.url))
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
+  // Register the layer's own type augmentation with the CONSUMER's TS program.
+  // Shipping the .d.ts in `files` is not enough: a consumer resolves this layer
+  // inside node_modules, and none of Nuxt's generated tsconfig include globs
+  // (`../*.d.ts`, `../../*.d.ts`, `../layers/*/*.d.ts`) reach there. It only
+  // typechecked here because the demo apps extend '..' by relative path.
+  hooks: {
+    'prepare:types': ({ references }) => {
+      references.push({ path: join(layerDir, 'page-meta.d.ts') })
+    },
+  },
   // The token stylesheet (imports tailwindcss + @nuxt/ui itself, so a consumer
   // does not add its own framework import — see README "CSS ownership").
   css: [join(layerDir, './assets/css/theme.css')],

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@thespielplatz/tsp-tools-theme",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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",
@@ -37,23 +37,32 @@
     "assets/css",
     "components",
     "composables",
+    "page-meta.d.ts",
     "plugins",
+    "docs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "lint": "eslint .",
-    "dev": "nuxi dev playground",
-    "dev:scoped": "nuxi dev scoped",
+    "docs:api": "node scripts/gen-api.mjs",
+    "docs:api:check": "node scripts/gen-api.mjs --check",
+    "dev": "node scripts/dev.mjs playground",
+    "dev:scoped": "node scripts/dev.mjs scoped",
     "build:playground": "nuxi build playground",
     "build:scoped": "nuxi build scoped",
     "typecheck": "nuxi typecheck playground && nuxi typecheck scoped",
-    "test:icons": "npm run build:playground && node scripts/check-icons.mjs",
-    "release": "npm run lint && npm run typecheck && npm run test:icons && npm publish"
+    "test:icons": "npm run build:playground && npm run build:scoped && node scripts/check-icons.mjs",
+    "gate": "npm run lint && npm run docs:api:check && npm run typecheck && npm run test:icons && npm run test:e2e",
+    "bump-version": "npm run gate && node scripts/bump-version.mjs && git push --follow-tags",
+    "release": "npm run gate && npm publish",
+    "test:e2e": "playwright test",
+    "test": "npm run test:icons && npm run test:e2e"
   },
   "dependencies": {
-    "@nuxt/icon": "~2.3.1",
-    "@nuxt/ui": "^4.10.0"
+    "@nuxt/icon": "~2.5.1",
+    "@nuxt/ui": "^4.11.1"
   },
   "peerDependencies": {
     "@iconify-json/tabler": "^1.2.0",
@@ -65,11 +74,13 @@
     }
   },
   "devDependencies": {
-    "@iconify-json/tabler": "^1.2.37",
-    "@nuxt/eslint-config": "^1.16.0",
-    "@types/node": "^26.1.2",
-    "eslint": "^10.8.0",
-    "nuxt": "^4.5.1",
-    "vue-tsc": "3.3.8"
+    "@iconify-json/tabler": "^1.2.38",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^26.6.2",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.11.0",
+    "nuxt": "^4.5.2",
+    "vue-tsc": "3.3.11"
   }
 }

package/page-meta.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+// `definePageMeta({ title })` is how a page tells <TspTopBar> what to show on
+// mobile, where the sidebar is hidden and nothing else says where you are.
+// Declared here so it typechecks in consumers, not only in this repo.
+declare module '#app' {
+  interface PageMeta {
+    /** Shown by TspTopBar when no `title` prop is passed. */
+    title?: string
+  }
+}
+export {}

package/plugins/01.tspColorMode.ts CHANGED Viewed

@@ -26,12 +26,24 @@ export default defineNuxtPlugin((nuxtApp) => {
     useHead({ htmlAttrs: { class: 'tsp-theme' } })
   }
   const isThemed = (path: string) =>
     options.apply === 'global' || path.startsWith(options.pathPrefix)
   const modeForPath = (path: string): TspMode =>
     isThemed(path) ? pref.value : options.publicMode
+  // ...and emit the MODE class server-side too. Without this the light/dark
+  // class was only ever written under `import.meta.client`, so the first paint
+  // was decided by colour-mode's own inline script reading its `nuxt-color-mode`
+  // localStorage key (default "dark") — not the `tsp_color_mode` cookie this
+  // layer introduced. Measured: `<html class="tsp-theme">` came back with no
+  // mode class for either cookie value, in both apps. The result was a
+  // wrong-mode flash on every cold load: a light user saw dark, and a scoped
+  // consumer's deliberately-light public area flashed dark on a first visit.
+  const ssrMode = computed(() => modeForPath(route.path))
+  useHead({ htmlAttrs: { class: () => ssrMode.value } })
   const apply = (path: string) => {
     const mode = modeForPath(path)
     colorMode.preference = mode