@thespielplatz/tsp-tools-theme 0.2.0 → 0.3.0

package/docs/api.md

@@ -0,0 +1,394 @@
+# API reference
+
+**Generated from the source by `scripts/gen-api.mjs` — do not edit.**
+`npm run docs:api` rewrites it; `npm run docs:api:check` is in the gate, so it cannot
+drift from the components. For what each component is *for*, and the rules that govern
+it, read [`design-system.md`](design-system.md) — this file is the signature only.
+
+28 components · 116 props · 4 composables.
+
+Every component is auto-imported; nothing needs an explicit import in a consuming app.
+A prop marked required has no default and the component will not render correctly without it.
+
+---
+
+## TspBanner
+
+A dismissible strip across the top of the content area. Its first job is the release announcement the tsp-release skill's `showBanner` flag turns on, but nothing here is release-specific: it is a banner.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `title` | `string` | `undefined` | Headline. Without it the banner is only its default slot. |
+| `icon` | `string` | `undefined` | Leading icon, `i-tabler-*`. |
+| `tone` | `'brand' \| 'neutral'` | `'brand'` | `brand` = amber accent edge, `neutral` = quiet. Neither is a fill. |
+| `dismissible` | `boolean` | `true` | Show the close button. The app decides whether it STAYS closed. |
+| `dismissLabel` | `string` | `'Dismiss'` | Accessible name for the close button. |
+
+**Slots** — default · `#action`
+
+**Emits** — `dismiss: []`
+
+## TspBrandTile
+
+The frame a service's mark sits in — size, radius and clipping. The artwork goes in the default slot; the layer ships no logo of its own and must not grow one (spec 02).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `size` | `'sidebar' \| 'hero'` | `'sidebar'` | `sidebar` = 24px (TspSidebar #brand), `hero` = 64px / 96px from sm up. |
+
+**Slots** — default
+
+## TspCodeBlock
+
+A block of configuration to copy — a JSON snippet, a shell line.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `code` | `string` | **required** | What is SHOWN. |
+| `copyValue` | `string` | `undefined` | What is COPIED, when that differs — e.g. the same config with the real key. |
+| `copyLabel` | `string` | `'Copy'` | Button label at rest. |
+| `copiedLabel` | `string` | `'Copied'` | Button label for the moment after a successful copy. |
+| `help` | `string` | `undefined` | One muted line under the block — e.g. what the placeholder stands for. |
+
+## TspContainer
+
+Centered content column.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `width` | `'app' \| 'site'` | `'app'` | `app` = 1152px, the logged-in measure. `site` = 1240px, the marketing one. |
+| `padded` | `boolean` | `true` | Vertical rhythm (`pt-10 pb-16`). Off for header/footer frames. |
+
+**Slots** — default
+
+## TspCopyButton
+
+Copy-to-clipboard button. Confirms by swapping its own icon for a tick for a moment — a copy that gives no feedback leaves you pressing it twice.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `value` | `string` | **required** | The string put on the clipboard. |
+| `label` | `string` | `'Copy'` | Button label at rest. |
+| `copiedLabel` | `string` | `'Copied'` | Button label for the moment after a successful copy. |
+
+## TspCopyField
+
+A read-only value with a copy button — an endpoint, a server URL, an API key.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `value` | `string` | **required** | What is shown and copied. Not rendered at all while masked. |
+| `label` | `string` | `undefined` | Field label above the value. |
+| `help` | `string` | `undefined` | One muted line under the field. |
+| `secret` | `boolean` | `false` | Mask the value behind a reveal. |
+| `revealLabel` | `string` | `'Show'` | Accessible name for the eye while the value is hidden. |
+| `hideLabel` | `string` | `'Hide'` | Accessible name for the eye while the value is shown. |
+| `copyLabel` | `string` | `'Copy'` | Accessible name for the copy button at rest. |
+| `copiedLabel` | `string` | `'Copied'` | Accessible name for it just after a successful copy. |
+
+**Slots** — `#help`
+
+## TspFooterRow
+
+One row of the sidebar footer nav — icon + label, styled exactly like a TspNavItem at rest. This exists because gage, pogo and trips each carried the same `footerRowClass` string in their own layout; no consumer should write it again (theme 0.3.0).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `to` | `string` | `undefined` | Internal route — renders a NuxtLink. |
+| `href` | `string` | `undefined` | External or non-router href — renders an <a>. |
+| `icon` | `string` | `undefined` | Tabler icon name. Every footer row carries one. |
+
+**Slots** — default
+
+## TspLanguageToggle
+
+DE/EN segmented control — the component gage, trips, pogo and tsp-tools each built by hand (theme 0.3.0).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `modelValue` | `string` | `undefined` | The active locale code. |
+| `locales` | `string[]` | `() => ['de', 'en']` | The codes to offer, in display order. |
+| `groupLabel` | `string` | `'Language'` | aria-label for the group. |
+| `labels` | `Record<string, string>` | `() => ({ de: 'German', en: 'English' })` | Accessible name per code (aria-label + title). Falls back to the code. |
+
+**Emits** — `'update:modelValue': [code: string]`
+
+## TspNavBadge
+
+The small pill on a nav row — stash's OWNER / MEMBER (spec 05).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `tone` | `'primary' \| 'neutral'` | `'neutral'` | `primary` = amber outline, `neutral` = grey. Outline only — a fill in the sidebar would read as a primary button (ADR 018). |
+
+**Slots** — default
+
+## TspNavGroup
+
+A nav item that owns sub-items (spec 04, variant A).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `to` | `string` | **required** | Route of the parent row itself — the group is a destination, not just a heading. |
+| `icon` | `string` | `undefined` | Tabler icon name for the parent row. |
+| `label` | `string` | **required** | Text of the parent row. |
+| `badge` | `string` | `undefined` | Optional pill on the right, e.g. a role. |
+| `badgeTone` | `'primary' \| 'neutral'` | `'neutral'` | Tone of that pill; see TspNavBadge. |
+
+**Slots** — default
+
+## TspNavItem
+
+Sidebar nav link: WHITE at rest, amber TEXT on a transparent background when active. Pass a Tabler icon name (`i-tabler-*`) and the route.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `to` | `string` | `undefined` | Internal route — renders a NuxtLink. |
+| `href` | `string` | `undefined` | External or non-router destination — renders an <a>. A section labelled "External" whose rows cannot leave the app is not much of a section. |
+| `target` | `string` | `undefined` | Only with `href`. Any target that leaves this context also gets `rel="noopener noreferrer"`. |
+| `icon` | `string` | `undefined` | Tabler icon name. Every nav row carries one. |
+| `badge` | `string` | `undefined` | Optional pill on the right of the row, e.g. a role. |
+| `badgeTone` | `'primary' \| 'neutral'` | `'neutral'` | Tone of the badge; see TspNavBadge. |
+
+**Slots** — default
+
+## TspNavLabel
+
+A nav row's label: truncated to the sidebar, with the full text revealed on hover after a short pause.
+
+No props.
+
+**Slots** — default
+
+## TspNavSection
+
+A break in the nav: a rule, optionally followed by a small label.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `label` | `string` | `undefined` | Omit for a bare divider. |
+
+## TspNavSubItem
+
+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.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `to` | `string` | **required** | Internal route. A child row is always internal. |
+| `icon` | `string` | `undefined` | Tabler icon name, e.g. `i-tabler-list-details`. |
+
+**Slots** — default
+
+## TspPageTabs
+
+Tabs across the top of an area, above the page title — the shape trips uses for Settings / MCP Server.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `items` | `{ label: string, to: string, icon?: string }[]` | **required** | One entry per view: `{ label, to, icon? }`. `to` is a ROUTE, so the back button works. |
+
+## TspReleaseNotes
+
+Release notes for one or more versions — the overview the tsp-release skill writes, rendered.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `releases` | `TspRelease[]` | **required** | Newest first. Mirrors the `tsp-release` skill's RELEASES shape, so a service can pass its own array straight through. |
+| `importantLabel` | `string` | `'Highlights'` | Heading over the `important` items. |
+| `otherLabel` | `string` | `'Also in this release'` | Heading over the `other` items. |
+| `beforeLabel` | `string` | `'Before'` | Caption on the left side of a before/after pair. |
+| `afterLabel` | `string` | `'After'` | Caption on its right side. |
+
+## TspSectionCard
+
+A titled content card: icon + title in a header row, content below.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `title` | `string` | `undefined` | Short card title. Omit for an untitled card — no empty heading is emitted. |
+| `icon` | `string` | `undefined` | Tabler icon name. Amber, because it labels rather than decorates. |
+
+**Slots** — default
+
+## TspSidebar
+
+App-shell sidebar frame (the generic structure from the piggybank admin). The app supplies content via slots; no app-specific branding/nav lives here.
+
+No props.
+
+**Slots** — `#brand` · `#footer` · `#nav`
+
+## TspSidebarFooter
+
+The sidebar bottom block, in the order spec 03 fixes:
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `user` | `string` | `undefined` | The username. Plain text, no icon. Use #user only if you need more. |
+| `userLabel` | `string` | `'User'` | Accessible name for the user row. |
+| `userIcon` | `string` | `'i-tabler-user-circle'` | Icon for the user row. Pass `undefined` for a bare name. |
+| `userTo` | `string` | `undefined` | Route to the user page. Given, the row becomes a link and can go active. |
+| `settingsTo` | `string` | `undefined` | Route to the settings page. Omit to drop the row. |
+| `settingsLabel` | `string` | `'Settings'` | Visible text of the settings row. |
+| `logoutTo` | `string` | `undefined` | Internal logout route. Use this or `logoutHref`, not both. |
+| `logoutHref` | `string` | `undefined` | External logout URL — the usual case with a hosted identity provider. |
+| `logoutLabel` | `string` | `'Logout'` | Visible text of the logout row. |
+| `modelValue` | `string` | `undefined` | Active locale (v-model). The language toggle renders only with `locales`. |
+| `locales` | `string[]` | `undefined` | Locale codes, e.g. `['de', 'en']`. The language row appears only with this — not every service is translated. |
+| `languageGroupLabel` | `string` | `'Language'` | Accessible name for the locale group. There is no visible label. |
+| `languageLabels` | `Record<string, string>` | `undefined` | Accessible names per code, e.g. `{ de: 'Deutsch' }`. The button itself shows the code. |
+| `githubLink` | `string` | `undefined` | Presence of this is what makes the project open source. |
+| `githubLabel` | `string` | `'GitHub'` | Accessible name for the GitHub icon. |
+| `supportEmail` | `string` | `'support@tsp.tools'` | Support address. One platform mailbox, so it has a default. |
+| `supportLabel` | `string` | `'Support'` | Accessible name for the support icon. |
+| `supportSubject` | `string` | `undefined` | Subject line. Defaults to one naming this app, so support can tell which. |
+| `supportBody` | `string` | `undefined` | First line of the body. Defaults to app + version, for the same reason. |
+| `appName` | `string` | `undefined` | This app's name, used in the support subject/body and nothing else. |
+| `tipJar` | `boolean` | `false` | The tip jar icon. Same destination for every service, so only a boolean. |
+| `tipJarLabel` | `string` | `'Tip jar'` | Accessible name for the tip-jar icon. |
+| `tipJarLink` | `string` | `'https://thespielplatz.com/tip-jar'` | Where it goes. One destination for the whole platform, so services do not set this. |
+| `version` | `string` | `undefined` | Version string for the badge, e.g. `v0.3.0`. Omit to drop the badge. |
+| `versionLink` | `string` | `undefined` | Release link for the badge. Ignored without `githubLink`. |
+| `versionUnread` | `boolean` | `false` | Mark the version badge as having unseen release notes. |
+| `toolOf` | `boolean` | `false` | The “A tool of tsp.tools” line. Off by default; only some services carry it. |
+| `toolOfLabel` | `string` | `undefined` | Leading words of the attribution. Left undefined so TspToolOf owns the default. |
+| `toolOfName` | `string` | `undefined` | The platform name in it. Same reason. |
+| `toolOfLink` | `string` | `undefined` | Where that name points. Same reason. |
+| `labelToLight` | `string` | `undefined` | Theme-toggle text while dark — it names the DESTINATION. |
+| `labelToDark` | `string` | `undefined` | Theme-toggle text while light. |
+| `ariaLabelToLight` | `string` | `undefined` | Its accessible name while dark. |
+| `ariaLabelToDark` | `string` | `undefined` | Its accessible name while light. |
+
+**Slots** — `#logout` · `#user`
+
+**Emits** — `'update:modelValue': [code: string]`
+
+## TspSiteFooter
+
+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.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `toolOf` | `boolean` | `false` | The “A tool of tsp.tools” line. Off by default; only some services carry it. |
+| `toolOfLabel` | `string` | `undefined` | Leading words of the attribution. Left undefined so TspToolOf owns the default. |
+| `toolOfName` | `string` | `undefined` | The platform name in it. Same reason. |
+| `toolOfLink` | `string` | `undefined` | Where that name points. Same reason. |
+
+**Slots** — `#actions` · `#brand` · `#links`
+
+## TspSiteHeader
+
+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.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `sticky` | `boolean` | `true` | Keep the bar at the top of the viewport. Ignored when `bare`. |
+| `bare` | `boolean` | `false` | No bar: no border, no background, not sticky. For landing pages. |
+
+**Slots** — `#actions` · `#brand` · `#nav`
+
+## TspThemeProvider
+
+Scoped-mode wrapper: marks a sub-area as themed. Everything inside resolves the tsp tokens (amber primary, anthracite/light surfaces); everything outside keeps default Nuxt UI. In global mode you don't need this — the colour-mode plugin puts `.tsp-theme` on <html> for you.
+
+No props.
+
+**Slots** — default
+
+## TspThemeToggle
+
+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).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `labelToLight` | `string` | `'Light'` | Visible label while dark (pressing switches to light). |
+| `labelToDark` | `string` | `'Dark'` | Visible label while light. |
+| `ariaLabelToLight` | `string` | `'Switch to light mode'` | aria-label while dark. |
+| `ariaLabelToDark` | `string` | `'Switch to dark mode'` | aria-label while light. |
+| `iconOnly` | `boolean` | `false` | Drop the visible label and render a compact icon button. |
+
+## TspToolOf
+
+“A tool of tsp.tools” — the platform attribution line.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `label` | `string` | `'A tool of'` | The leading words. |
+| `name` | `string` | `'tsp.tools'` | The platform, not the service. A service never names itself here. |
+| `link` | `string` | `'https://tsp.tools'` | Where the name points. |
+
+## TspTopBar
+
+Mobile top bar — only below `sm`, where the sidebar has become a drawer.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `title` | `string` | `undefined` | The current page's name. Nothing else on a mobile screen says where you are. Omitted, it is derived from the route. |
+| `menuLabel` | `string` | `'Open menu'` | Accessible name for the burger button. |
+
+**Slots** — `#brand`
+
+## TspUserCard
+
+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).
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `name` | `string` | **required** | Display name. |
+| `accountLabel` | `string` | `'tsp.tools account'` | Which account this is — shown under the name. |
+| `accountId` | `string` | `undefined` | The account id. Omit to hide the whole id block. |
+| `idLabel` | `string` | `'tsp.tools ID'` | Label over the account id. |
+| `manageLink` | `string` | `undefined` | Where “manage account” goes. Omit to hide the link. |
+| `manageLabel` | `string` | `'Manage account in Logto'` | Text of the manage-account link. |
+| `revealLabel` | `string` | `'Show ID'` | Accessible name for the eye while the id is hidden. |
+| `hideLabel` | `string` | `'Hide ID'` | Accessible name for it while the id is shown. |
+
+## TspVersionBadge
+
+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.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `version` | `string` | **required** | The version string, shown as-is, e.g. `v0.3.0`. |
+| `href` | `string` | `undefined` | Release link. Omitted for closed-source projects, which renders a span. |
+| `unread` | `boolean` | `undefined` | There are release notes the user has not seen. |
+
+## TspWordmark
+
+Brand wordmark: the app's name in white, terminated by an amber dot.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `name` | `string` | **required** | The app name, lowercase. The amber dot is appended for you. |
+
+---
+
+## Composables
+
+Auto-imported like the components.
+
+### useTspColorMode
+
+The themed area's own colour-mode preference, remembered in a cookie so it is readable during SSR and survives reloads. Kept separate from @nuxtjs/color-mode's global state so that forcing the public area to `publicMode` (scoped mode) can never erase the user's choice.
+
+Returns `{ pref, toggle }`.
+
+Also exports: `useTspThemeOptions`.
+
+### useTspCopy
+
+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.
+
+Returns `{ copied, copy }`.
+
+### useTspNavDrawer
+
+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.
+
+Returns `{ isOpen, open, close, toggle }`.
+
+### useTspReveal
+
+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.
+
+Returns `{ revealed, toggle, mask }`.