paneltir 0.6.0

package/README.md

@@ -0,0 +1,404 @@
+# Paneltir
+
+**Paneltir** is the DFKlabs UI kit for administration panels. It owns
+**structure and behaviour** — page frame, a board with touch-ready drag and
+drop, detail sheets, theming — and never colour or brand. Each project hands
+it a palette and that is the whole customisation.
+
+> ⚠️ **Proprietary software.** This repository is private and is not open
+> source. Access is granted only to authorised projects; copying,
+> redistribution or modification without written permission is prohibited.
+> See [`LICENSE`](./LICENSE).
+
+🌐 **Site:** [paneltir.dfklabs.com](https://paneltir.dfklabs.com) —
+[live demo](https://paneltir.dfklabs.com/demo) ·
+[project panel](https://paneltir.dfklabs.com/admin) (password protected)
+
+## Repository contents
+
+| Path | What it is |
+| --- | --- |
+| `src/` | The kit: React + TypeScript components with a stylesheet per component. |
+| `src/themes/presets.ts` | Base palettes: `cyberpunkTheme` (Night City), `midnightTheme`, `oldMoneyTheme`. |
+| `site/` | The website: landing, live demo, the project's own panel and the legal pages. |
+| `site/src/data/panel-state.json` | The board behind `/admin` — panel content as version-controlled data. |
+| `middleware.ts` | Vercel edge middleware that password-protects `/admin` and the panel API. |
+| `api/panel-state.ts` | Serverless function that commits the board back to this repository. |
+| `.claude/skills/todo/SKILL.md` | `/todo` — how Claude reads the board and what each intent obliges. |
+| `examples/demo/` | A minimal Vite app kept as a starting template for a consumer project. |
+| `INSTALL.md` | Install instructions, written for Claude rather than for a human reader. |
+| `CLAUDE_MD_SNIPPET.md` | The block to paste into each consumer project's `CLAUDE.md`. |
+| `fingerprint.json` | SHA-256 of the whole repository and of every file (see below). |
+| `renovate.json.example` | Renovate config so consumers get a pull request on every new tag. |
+
+## Components
+
+| Export | Purpose |
+| --- | --- |
+| `DashboardThemeProvider` / `useDashboardTheme` | Turns the project palette into `--pt-color-*` variables. |
+| `DashboardHeader` | Header with wordmark, status line and an action link. |
+| `AlertBanner` | Full-width alert with an optional retry action. |
+| `StatTile` / `StatTileGrid` | Large metrics with a semantic tone and a calm state for zero. |
+| `HealthPill` / `HealthPillRow` | System facts: ok, warning, bad, unknown. |
+| `FilterChip` / `FilterChipRow` | Filters with counters. |
+| `Board` / `Card` / `moveCardInColumns` | Kanban board with pointer-event drag and drop and edge autoscroll. |
+| `DetailSheet` / `DetailSection` | Bottom sheet under 760px, centred dialog above it, from one markup. |
+| `useDelegatedClick` / `useMediaQuery` | Supporting hooks. |
+
+## Installation
+
+The kit ships as a Git dependency — no npm registry involved. Always pin a
+tag rather than a branch, so an unfinished push cannot reach a project:
+
+```bash
+npm install paneltir
+
+# or, without npm access, straight from the repository:
+# npm install github:daifukus/paneltir#v0.6.0
+```
+
+Installing from Git runs the `prepare` script, which builds `dist/`, so the
+repository does not need to carry build output.
+
+### Private repository
+
+Whoever runs `npm install` needs Git read access to this repository:
+
+- **Locally**, an existing SSH key for GitHub is enough — `npm install
+  github:...` reuses it.
+- **In CI or on a deploy platform**, that machine needs its own access: a
+  read-only deploy key, or a fine-grained GitHub token scoped to this
+  repository and stored as a pipeline secret. **Never put a token in the
+  dependency URL** — it would be committed in plain text in every consumer
+  repository. Configure it in the machine's `.npmrc` or credential helper
+  instead.
+
+### Installing it with Claude
+
+Paste this into the project where the kit should go:
+
+> Install `paneltir` following the instructions in
+> `node_modules/paneltir/INSTALL.md`, pinned to the tag we agreed on.
+
+`INSTALL.md` is written as an instruction for the agent: it looks for the
+palette the project already has before inventing one, maps it to the token
+roles and wires up `DashboardThemeProvider`, so the result always looks like
+*that* project.
+
+`INSTALL.md` is read once, at install time. To keep the "never edit
+`node_modules/paneltir`" rule alive across day-to-day requests, also paste the
+block from [`CLAUDE_MD_SNIPPET.md`](./CLAUDE_MD_SNIPPET.md) into the project's
+own `CLAUDE.md`, which is reloaded every session.
+
+## Base themes
+
+For a project without a visual identity yet (see `INSTALL.md`, step 3), the
+package ships three palettes: `cyberpunkTheme` (crimson surfaces and Night
+City yellow — the site's default), `midnightTheme` (neutral) and
+`oldMoneyTheme` (bottle green, muted gold). All three follow the same rules —
+a single accent, four semantic colours kept apart from it — and differ only in
+the choice of colour:
+
+```tsx
+import { DashboardThemeProvider, cyberpunkTheme } from 'paneltir'
+
+<DashboardThemeProvider tokens={cyberpunkTheme}>...</DashboardThemeProvider>
+```
+
+They are a starting point, not an identity: replace them as soon as the
+project has its own.
+
+## The website
+
+`site/` is what gets published to
+[paneltir.dfklabs.com](https://paneltir.dfklabs.com):
+
+- **`/`** — the landing: what the kit solves, its public surface, the base
+  themes and how it installs.
+- **`/demo`** — a public panel with fictional data, so the drag and drop, the
+  filters, the detail sheet and the theme switcher can be tried without an
+  account.
+- **`/admin`** — the project's own panel, password protected, and fully
+  editable: add a card with the column's **+**, drag it by its grip, open it to
+  set priority, risk, who it waits on, an **order for Claude** and one of nine
+  **intents**, tick checklist steps and leave notes. **Save to GitHub** commits
+  `site/src/data/panel-state.json`, so every change to the board is a diff in
+  version control. It also carries a **Functions** section describing what the
+  kit gives a project and how Claude should work with it.
+- **`/terms`, `/license`, `/copyright`** — the legal pages.
+
+```bash
+npm install        # builds dist/, which the site consumes as file:..
+npm run site:dev   # landing, demo and panel on http://localhost:5173
+```
+
+### Panel access
+
+Opening `/admin` without a session lands on `/login`, a sign-in screen on the
+site rather than the browser's own credential dialog. The password is posted to
+`api/login.ts`, which answers with a signed, HttpOnly session cookie;
+`middleware.ts` then verifies it before serving `/admin`, the panel's own
+JavaScript bundle or the panel API. Sessions last eight hours, and **Sign out**
+lives in the panel's settings sheet.
+
+Set these in the Vercel project (Settings → Environment Variables):
+
+| Variable | Value |
+| --- | --- |
+| `ADMIN_PASSWORD` | The panel password. Required — without it `/admin` answers 503 instead of becoming public. |
+| `SESSION_SECRET` | Optional key for signing sessions. Defaults to `ADMIN_PASSWORD`, so changing the password ends every session already issued. |
+| `GH_TOKEN` | Fine-grained token with *contents: read and write* on this repository only. Lets the panel commit its board. |
+| `PANEL_REPO` | Optional `owner/repo`, `daifukus/paneltir` by default. |
+| `PANEL_BRANCH` | Optional branch, `main` by default. |
+
+None of these live in the repository, and `GH_TOKEN` never reaches the browser:
+it is read inside the serverless function only.
+
+### The board is a queue
+
+A card is not a note, it is an instruction. Beyond a title and a body it
+carries a **column** (`ideas`, `next`, `doing`, `yours`, `done`), a
+**priority**, a **risk** — what it costs if it goes wrong, not how soon it is
+wanted — **who it waits on**, an **order** flag meaning "I am asking you to do
+this", and an **intent**: one of nine values that says *how* to do it and beats
+anything the agent would otherwise decide. Three of them — `explain`, `askme`,
+`hold` — are refusals to act, which is the only way to say "not yet" in a way
+that survives a session boundary.
+
+`.claude/skills/todo/SKILL.md` is the other half: it turns those fields into a
+work list, in order, and says what each one obliges. Run `/todo` and the panel
+stops being a status page and becomes the interface.
+
+### The panel writes its own state
+
+Moving a card in `/admin` marks the board as changed and a **Save to GitHub**
+button appears in the header. Saving POSTs the state to
+`/admin/api/panel-state`, which is `api/panel-state.ts`: it re-checks the same
+credentials, validates the payload, and commits
+`site/src/data/panel-state.json` on `main` through the GitHub API using
+`GH_TOKEN`. So an edit made from the board is an ordinary commit with a diff,
+an author and a history — and the deploy that follows is what makes it visible
+on the site.
+
+The write sends the file's current blob SHA, so if the file changed in the
+repository meanwhile the save is rejected with a conflict instead of silently
+overwriting that change.
+
+## Basic usage
+
+```tsx
+import {
+  DashboardThemeProvider,
+  DashboardHeader,
+  StatTileGrid,
+  StatTile,
+  Board,
+  Card,
+  DetailSheet,
+  DetailSection,
+  moveCardInColumns,
+  type DashboardThemeTokens,
+  type BoardColumnData,
+} from 'paneltir'
+import 'paneltir/style.css'
+
+// The project palette — the only thing that changes between projects.
+const theme: DashboardThemeTokens = {
+  ground: '#0b0c10',
+  groundRaised: '#14161c',
+  panel: '#181a21',
+  raised: '#20232b',
+  line: 'rgba(255,255,255,0.13)',
+  lineFaint: 'rgba(255,255,255,0.07)',
+  ink: 'rgba(255,255,255,0.92)',
+  inkDim: 'rgba(255,255,255,0.62)',
+  inkFaint: 'rgba(255,255,255,0.34)',
+  accent: '#5b8cff',
+  danger: '#ff5c5c',
+  warning: '#f5b74c',
+  success: '#3ecf8e',
+  neutral: '#8a8f98',
+}
+
+function AdminDashboard() {
+  const [columns, setColumns] = React.useState<BoardColumnData[]>(initialColumns)
+
+  return (
+    <DashboardThemeProvider tokens={theme}>
+      <DashboardHeader wordmark="My project" status="3 pending" linkLabel="Sign out" />
+
+      <StatTileGrid>
+        <StatTile label="Open" value={12} tone="warning" />
+        <StatTile label="Overdue" value={0} isZero />
+      </StatTileGrid>
+
+      <Board
+        columns={columns}
+        onMove={(move) => setColumns((current) => moveCardInColumns(current, move))}
+        renderCard={(card, index, columnId) => (
+          <Card
+            cardId={card.id}
+            columnId={columnId}
+            index={index}
+            title={card.title as string}
+            priorityColor={theme.danger}
+            tags={[{ label: 'blocked', tone: 'danger', emphasize: true }]}
+            progress={{ done: 2, total: 5 }}
+            onClick={() => openDetail(card.id)}
+          />
+        )}
+      />
+
+      <DetailSheet open={detailOpen} onClose={closeDetail} ariaLabel="Card detail">
+        <DetailSection title="Assigned to" subtitle="who is working on it">
+          ...
+        </DetailSection>
+      </DetailSheet>
+    </DashboardThemeProvider>
+  )
+}
+```
+
+## What the library actually solves
+
+- **Pointer-event drag and drop**, not the HTML5 drag API, which never fires
+  on iOS touch.
+- **Edge autoscroll on requestAnimationFrame**, reading the pointer from a
+  ref rather than from `pointermove`, which stops firing while a finger is
+  held still against the edge.
+- **Scroll-snap disabled during a drag**, so the autoscroll does not fight the
+  board's snap.
+- **A real floating clone** (a DOM clone, not a redrawn approximation) that
+  follows the pointer.
+- **A single `moveCardInColumns`** — moving an item between arrays by index is
+  exactly where an off-by-one hides when four projects each rewrite it.
+
+## Theming
+
+All colour enters through `DashboardThemeTokens` and leaves as `--pt-color-*`
+variables inside `.pt-theme-root`. The library ships no defaults on purpose:
+a forgotten token renders without colour, which is noticed immediately,
+instead of silently inheriting something generic. Every role is documented in
+`src/theme/tokens.ts` and in the published `.d.ts`.
+
+## Change fingerprint (`fingerprint.json`)
+
+`fingerprint.json` holds a SHA-256 computed over every tracked file, plus a
+hash per file. It ships with the package, so in a consumer project it sits at
+`node_modules/paneltir/fingerprint.json`.
+
+It exists so Claude — or any script — can tell in a single read whether the
+kit changed since it was last reviewed, instead of spending tokens re-reading
+code and documentation that did not move. The block in `CLAUDE_MD_SNIPPET.md`
+records the last integrated hash in each project; when it matches, there is
+nothing to read. When it differs, the `files` map names exactly which files
+moved.
+
+```bash
+npm run fingerprint         # regenerate it (before every commit)
+npm run fingerprint:check   # fail if stale (this is what CI runs)
+node scripts/fingerprint.mjs --print   # print just the hash
+```
+
+It is only rewritten when the global hash changes, so it never produces empty
+diffs.
+
+## Deployment (Vercel)
+
+The site is served from Vercel. The configuration lives in `vercel.json`; in
+the Vercel project leave **Root Directory empty** (the repository root) and
+Framework Preset as "Other": the install builds the kit (`dist/`) first and
+the site second, and the output is `site/dist`. Every merge to `main` deploys.
+Remember to set `ADMIN_PASSWORD` before the first deploy.
+
+Changing a Vercel setting only affects new deployments: redeploy, or merge a
+pull request, for it to take effect. Keep the repository connected to a single
+Vercel project — two projects on the same repository build twice and only one
+can hold the domain.
+
+### Only `main` deploys
+
+`vercel.json` sets `git.deploymentEnabled` so Vercel builds `main` and nothing
+else. Branch previews were spending the free plan's allowance of 100
+deployments a day — once it runs out, *nothing* deploys for 24 hours,
+production included. Pull requests lose their preview URL, which costs little:
+CI already builds the kit, the site and the starter template on every pull
+request.
+
+If previews are wanted back, delete that `git` block, and keep an eye on the
+daily count. The same switch exists in the dashboard under Settings → Git,
+and the dashboard is authoritative if the two ever disagree.
+
+### If production never deploys
+
+Vercel refuses to build a commit whose author GitHub cannot verify, and it
+says so on the pull request ("GitHub couldn't verify an account for commit").
+Merge commits created from the GitHub UI or API carry the account's primary
+email, so if that address is a private relay the production build is blocked
+while branch previews still work.
+
+Two fixes, and doing both is fine:
+
+1. **At the source.** GitHub → Settings → Emails → enable *Keep my email
+   address private*. From then on web and API commits are authored as
+   `<id>+<user>@users.noreply.github.com`, which is always verifiable.
+2. **Independently of Git.** `.github/workflows/deploy.yml` pings a Vercel
+   deploy hook on every push to `main`. Create the hook in Vercel → Settings →
+   Git → Deploy Hooks (branch `main`) and store its URL as the
+   `VERCEL_DEPLOY_HOOK_URL` secret in this repository. Without the secret the
+   job is a no-op, so nothing breaks if it is not configured.
+
+### Does the build need a GitHub token?
+
+The **build** does not: the site consumes the kit as `file:..`, so Vercel never
+fetches this repository over the network, and its GitHub integration already
+has read access to the source.
+
+The **panel** does, to write: `GH_TOKEN` is what lets `api/panel-state.ts`
+commit the board. Keep it fine-grained, scoped to this repository, with
+*contents: read and write* and nothing else. It is only ever read server-side.
+
+## Updating consumer projects
+
+### By hand
+
+1. Make the change here with the version bump in `package.json`, merge it to
+   `main`, and `tag-release.yml` creates the `vX.Y.Z` tag automatically.
+2. In each consumer project: `npm install paneltir@X.Y.Z`, or
+   `npm install github:daifukus/paneltir#vX.Y.Z` without npm access.
+3. Claude can do that bump and run the dashboard smoke test in each
+   repository — it is mechanical, not a reinterpretation.
+
+### With automatic pull requests
+
+Install the [Renovate app](https://github.com/apps/renovate) on each consumer
+project and copy [`renovate.json.example`](./renovate.json.example) as
+`renovate.json` at its root. From then on, every new tag opens a pull request
+with the bump already applied.
+
+## Local development
+
+```bash
+npm install
+npm run dev        # tsup --watch
+npm run typecheck  # tsc --noEmit
+npm run build      # produces dist/
+npm run verify     # typecheck + build + fingerprint:check (what CI runs)
+```
+
+To try it against a project before tagging, `npm link` (or a temporary
+`file:../paneltir` dependency) avoids tagging on every iteration.
+
+## Roadmap
+
+- Type sizes as `--pt-font-size-*` tokens instead of per-component values.
+- Drop placeholder matching the dragged card's real height.
+- Tests for `moveCardInColumns` (same index, end of column, empty columns).
+- Validate the token system against light surfaces.
+
+## License
+
+Copyright © 2026 DFKlabs. All rights reserved. Use is restricted to the
+projects the holder authorises — see [`LICENSE`](./LICENSE) for the full
+terms, and the [License page](https://paneltir.dfklabs.com/license) for a
+plain-English summary.