@viglet/viglet-design-system 2026.3.2 → 2026.3.4

package/README.md

@@ -1,13 +1,102 @@
 # Viglet Design System
 
-Shared component library, design tokens, hooks, utilities, and i18n for Viglet products (Turing, Dumont, Shio).
+Shared component library, design tokens, hooks, utilities, and i18n for the six
+applications that install it: the Turing, Dumont and Shio consoles,
+the Cloud Console, the Cloud Home, and Schools. `consumers.json` is the list,
+and it is what the guards read.
+
+**[Browse the component catalogue](https://openviglet.github.io/viglet-design-system/)** — every
+component, its variants and its props, rebuilt on each commit to `2026.3`. Look
+there before writing a component: the catalogue is the answer to "does this
+already exist".
+
+The six applications that install this package are the consumers it holds itself
+to, declared in [`consumers.json`](consumers.json) rather than remembered: each
+entry names its framework, its chrome, the accent it renders with and the
+subpaths it takes, and CI refuses prose that names a subset as though it were
+the whole set. A seventh is one entry there, and the checks widen with it.
+
+Three are Vite consoles (Turing, Shio, Dumont), one is a Vite platform home
+(the Cloud Home), and two are Next applications (the Cloud Console and Schools).
+The split matters: a Next consumer takes no `./router` and no `./vite`.
 
 ## Installation
 
 ```bash
-npm install @viglet/viglet-design-system
+pnpm add @viglet/viglet-design-system
 ```
 
+## Trying a change in a product before publishing
+
+A change here is a change to shared chrome, so the question is always what it
+does to Shio, Turing, Dumont, the Cloud Console, the Cloud Home and Schools —
+and the answer should not require a publish. `use:local` walks a products root,
+so it reaches the first three; the other three are checked out elsewhere and
+`npm pack` into them is the loop until that changes (VDS73). From this checkout:
+
+```bash
+pnpm use:local           # build, then push dist into every 2026.3 product on disk
+pnpm use:local --list    # show what it would write to, and stop
+```
+
+It finds the consumers by reading their `package.json`, and finds where each one
+keeps the installed copy by following the link its own package manager made, so
+neither a version bump nor a switch of package manager breaks the loop. Nothing
+in the product's manifest or lockfile changes: `pnpm install` in the product puts
+the published build back.
+
+Pass directories to narrow it, and `--no-build` to reuse the `dist` already on
+disk:
+
+```bash
+pnpm use:local ../shio/2026.3/shio-react --no-build
+```
+
+One thing it refuses to do: push over a tree whose dependencies are behind. It
+writes files, and files cannot re-resolve a dependency — so if a range moved
+here since the product last installed, the manifest it copies would ask for a
+version the directory beside it does not have, and the product would fail to
+build on symbols that version does not export. It names those packages and
+stops. That is a real limit rather than a check to switch off: a range that
+moved reaches a product through a release, not through this. `--skip-dep-check`
+pushes anyway when you know why you want it.
+
+## Catching a duplicate before it drifts
+
+The package ships `dist/exports.json` — every name it exports, per entry point —
+and a CLI that reads it. Run it in the product's own CI:
+
+```bash
+viglet-ds-check-duplicates src
+```
+
+It fails, naming the import that replaces each local copy:
+
+```
+src/components/page-header.tsx:18  declares PageHeader
+    replace it with:  import { PageHeader } from "@viglet/viglet-design-system/router"
+```
+
+One-line re-export shims are the sanctioned pattern and are skipped. When a
+collision is deliberate — a product component that renders that product's own
+data and merely shares a name — keep it by writing the reason in the file:
+
+```ts
+// viglet-ds-allow-duplicate AppFooter -- renders Shio's build version
+```
+
+In a product's workflow, it is one step beside the lint:
+
+```yaml
+      - name: No local copy of a shared component
+        run: pnpm exec viglet-ds-check-duplicates src
+```
+
+Add `--warn` to report without failing while the existing collisions are being
+worked through, and drop it once the count is zero. `--json` prints the findings
+for a bot to read; `--manifest <path>` checks against an export list other than
+the installed one.
+
 ## Setup
 
 ### 1. Import styles
@@ -24,6 +113,37 @@ Or in your entry TypeScript/JavaScript:
 import "@viglet/viglet-design-system/styles";
 ```
 
+The brand faces are a **separate import**, and one you probably want:
+
+```css
+@import "@viglet/viglet-design-system/styles";
+@import "@viglet/viglet-design-system/fonts";
+```
+
+They used to be inside `./styles`, where they were 741 KB of its 964 KB —
+Vite's library mode inlines every asset regardless of `assetsInlineLimit`, so
+every subset of Inter and Plus Jakarta Sans was base64 in the CSS, twice over
+because the preset imported them as well. Base64 of an already-compressed woff2
+does not compress again, which is why 2,276 rules gzipped to 594 KB. Splitting
+them takes `./styles` to 31 KB gzipped.
+
+`./fonts` is 5 KB of rules pointing at 11 `.woff2` files shipped beside it in
+`dist/fonts/`. Nothing in it resolves through your `node_modules`, and your CDN
+and browser cache the faces apart from the rules — so a change to any rule no
+longer re-downloads every font, and a product already serving Inter can drop
+this copy.
+
+**A page fetches about 77 KB of that, not 272 KB.** Each face carries a
+`unicode-range`, so the browser asks only for the subsets your text needs; an
+English or Portuguese page takes `latin` and nothing else, the accented
+characters Portuguese uses being Latin-1 rather than `latin-ext`.
+`size-budget.json` records both numbers, and CI fails if either moves — or if
+the faces stop being subsetted at all.
+
+**Upgrading:** add the second line, or the type falls back through `--font-sans`
+to `system-ui`. That is a real look rather than a broken one, but it is not the
+one the catalogue shows.
+
 ### 2. Initialize i18n
 
 ```ts
@@ -69,6 +189,42 @@ function App() {
 }
 ```
 
+`ThemeProvider` is a thin wrapper over [`next-themes`](https://github.com/pacocoursey/next-themes),
+which is a peer dependency. Three consequences worth knowing:
+
+- **It renders on a server.** No `localStorage` is read during render, so a
+  server-rendered or React Server Components consumer can mount it.
+- **There is one theme source.** This package's `Toaster` reads `next-themes`
+  directly, so mounting both used to run two theme systems writing the class
+  from two storage keys. It no longer does.
+- **You can skip it.** A consumer that mounts `next-themes`'s own provider gets
+  the same result, and `useTheme` from here reads that one — useful when a
+  framework already sets the theme up for you.
+
+`useTheme()` returns `{ theme, setTheme }`, where `theme` is the *setting*
+(`"light" | "dark" | "system"`) rather than the resolved colour.
+
+### React Server Components
+
+The published entries carry a `"use client"` directive where they need one, so a
+Next App Router server component can import this package without adding a
+directive of its own:
+
+| Entry | |
+|---|---|
+| `.`, `./bento`, `./router`, `./floating-formulas-bg`, `./i18n` | client — they reach React state, context or a browser API |
+| `./assets`, `./vite` | server-renderable — logo data, and a build-time Vite plugin |
+
+`./i18n` is the one worth pointing at: it looks pure, and it pulls
+`i18next-browser-languagedetector`. `./assets` staying unmarked is deliberate —
+a server component can read a product logo without a client boundary.
+
+**The directive is not the whole story for a Next consumer.** `./router` and
+`./bento` import `react-router-dom` (see the peer note further down), which an
+App Router application does not use. Being marked client makes them *compile*
+under RSC; it does not make them route. Today a Next consumer takes the root
+entry, `./assets`, `./floating-formulas-bg` and the styles.
+
 ### 4. Setup Axios CSRF protection
 
 ```ts
@@ -107,19 +263,40 @@ import {
 
 ```tsx
 import {
-  PageHeader,
-  SubPageHeader,
-  GridList,
   DialogDelete,
-  BlankSlate,
   LoadProvider,
-  NavUser,
+  GradientButtonLink,
   AppFooter,
   LanguageSelect,
   ModeToggle,
 } from "@viglet/viglet-design-system";
 ```
 
+A page's chrome — its header, its list, its sidebar — comes from the
+[bento layer](#the-bento-layer) rather than from here. Read the next section
+before reaching for `PageHeader`, `GridList` or `InternalSidebar`.
+
+### Two eras, and which one a new page should use
+
+This package exports two complete page vocabularies. The **console era** is what the consoles ship on today; the **[bento layer](#the-bento-layer)** is the current one, and Turing has cut over to it. Every console-era export is marked `@deprecated` in its own types, so an editor strikes it through and offers the swap.
+
+Nothing is being removed. No product has started cutting over, and a removal will get its own roadmap line rather than arriving as a side effect of this notice — so existing pages keep working and need no rush.
+
+| Console era | Use instead | |
+|---|---|---|
+| `PageHeader` | `BentoHero` | Same title/subtitle/icon, plus a tone — the chip follows the product accent. |
+| `SubPageHeader` | `BentoHero` | With `BentoBackLink` for the back target and `BentoActionsMenu` for the menu. |
+| `StickyPageHeader` | `useBentoScrollFade` | The scroll state is separated from the chrome, so it also drives `BentoScrollSaveBar`. |
+| `GridList` | `BentoListPage` | `BentoTileGrid` is the mosaic alone, for a page with its own chrome. |
+| `BlankSlate` | `BentoEmptyState` | |
+| `InternalSidebar` | `BentoNavRail` | The rail takes its nav array as a prop instead of importing routes. |
+| `NavMain` | `BentoNavRail` | |
+| `NavUser` | `BentoUserMenu` | Routes and feature flags arrive as props. |
+| `SubPage` | `BentoEntityShell` | Renders through a render prop, so the shell never learns what an entity is. |
+| `Page`, `PageContent` | — | No single replacement, deliberately: the shell is where a product is itself. Compose `BentoNavRail`, `BentoUserMenu` and `BentoCommandPalette`. |
+
+`DialogDelete`, `LoadProvider` and `GradientButtonLink` are **not** console-era — the bento layer uses them itself, and they are not deprecated.
+
 ### Hooks
 
 ```tsx
@@ -146,6 +323,27 @@ import {
 } from "@viglet/viglet-design-system";
 ```
 
+`exportToXlsx(data, headers, filename, sheetName?)` takes an optional sheet name; without one the sheet is named after `filename` (it used to be `Logging`, whatever you exported). The header row is written from `headers`, so an export with no rows still arrives with its column titles rather than as an empty file.
+
+### Product logos
+
+```tsx
+import { productLogos, type ProductId } from "@viglet/viglet-design-system/assets";
+```
+
+Their own subpath, not the root barrel. Vite's library mode inlines every asset
+regardless of `assetsInlineLimit`, so anything the root barrel could reach was
+base64 inside the root entry — `productLogos` names all four logos, and one of
+them is 1.24 MB, which put 1.90 MB of PNG in front of every consumer. Nothing
+renders that one: `VigletAppSwitcher` draws the Viglet Cloud entry with an icon.
+Moving the map here left the root entry 56% lighter, and the size gate now
+refuses any single inlined asset over 256 KB.
+
+`VigletAppSwitcher` still imports the three logos it draws, so it needs no
+change — and those three are now 256px rather than 1024–2375px, which is nine
+times the 28 pixels the switcher renders them at. A test holds that ceiling,
+because an asset this package can reach is an asset it ships.
+
 ### Models
 
 ```tsx
@@ -164,20 +362,47 @@ Accordion, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, Dialog, Drawer, Dr
 
 ### App Components (23 components)
 
-AppFooter, BadgeColorful, BadgeLocale, BlankSlate, DialogDelete, GridList, InternalSidebar, LanguageSelect, LoadProvider, ModeToggle, NavMain, NavSecondary, NavUser, Page, PageContent, PageHeader, SubPage, SubPageHeader, ThemeProvider
+AppFooter, BadgeColorful, BadgeLocale, DialogDelete, GradientButtonLink, LanguageSelect, LoadProvider, ModeToggle, NavSecondary, ThemeProvider
+
+Console-era, `@deprecated`, still exported — see [the swap table](#two-eras-and-which-one-a-new-page-should-use): BlankSlate, GridList, InternalSidebar, NavMain, NavUser, Page, PageContent, PageHeader, StickyPageHeader, SubPage, SubPageHeader
 
 ### Hooks
 
 `useIsMobile`, `useDateLocale`, `useGridAdapter`, `useSubPageBreadcrumb`
 
+`useGridAdapter(data, config)` tracks each extractor in `config`, not the object holding them, so a `url` builder that closes over a route param or a locale re-maps the rows when it changes. Pass the config inline if you like — keep the extractors themselves stable (a field name, a module-level function, a `useCallback`) and the memo holds.
+
 ### Contexts
 
 `BreadcrumbProvider` / `useBreadcrumb`, `UserProvider` / `useCurrentUser`, `ThemeProvider` / `useTheme`
 
+`useCurrentUser()` returns `status` (`"loading" | "ready" | "failed"`) and `error` alongside `user` and `refreshUser`. Read `status` rather than inferring one from an empty `user` — the same empty object means a request that has not settled, a session that expired, and an account with no username. A rejecting `fetchUser` sets `status: "failed"` and is not rethrown.
+
 ### Design Tokens
 
 OKLCH-based color system with light/dark mode, CSS variables for theming, consistent radius scale, chart palette, sidebar theme, animations.
 
+**The brand accent is one token, set once.** The tinted icon chip in a page header, the ring around it, an accented label and the solid primary fill all derive from two gradient stops, so a product picks its colour at the root rather than in every component:
+
+```css
+:root {
+  --vg-accent-from: oklch(70.5% 0.213 47.604);
+  --vg-accent-to:   oklch(64.6% 0.222 41.116);
+  --vg-accent-text: oklch(55.3% 0.195 38.402);  /* readable on light */
+  --vg-accent-text-dark: oklch(75% 0.183 55.934);  /* readable on dark */
+}
+```
+
+The tint, the strong tint and the hairline (`--vg-accent-surface`, `--vg-accent-surface-strong`, `--vg-accent-line`) are `color-mix` over `--vg-accent-from`, so they follow automatically; only the readable foreground is stated, because contrast is not a mix away. Use `--vg-accent-fg` in a component — it is already resolved for the current theme, so no `dark:` twin is needed.
+
+**Declare them on `:root`, not on a wrapper.** A custom property substitutes its `var()` references where it is *declared*, so the derived tokens above are mixed against the `--vg-accent-from` declared in the preset's `:root`. Re-keying a subtree moves what a utility class mixes on the element — the chip, the solid fill — and leaves the tint, the hairline and the button fill at the root's value. The result looks like a component that half-ignores the theme.
+
+Three utility classes cover the common shapes: `vg-accent-chip` (the tinted gradient chip — pair it with Tailwind's `ring-1`), `vg-accent-text` (an accented label or icon), and `vg-accent-solid` (a solid gradient fill).
+
+`GradientButton` and `GradientSwitch` follow the accent in their primary variants (`default`, `outline`, `ghost`), so a re-key reaches the buttons too; their `secondary`, `destructive` and `success` variants keep fixed semantic hues, because "destructive" does not change colour with the brand.
+
+This is separate from a component's **colour palette**. `SectionCard` (`blue | violet | emerald | amber | rose | cyan`) and `StickySaveBar` (`gray | blue | orange | green`) are keyed by hue — the caller picked that colour deliberately — so re-keying the accent leaves them alone, the same way it leaves the [bento tones](#the-bento-layer) alone.
+
 ### i18n
 
 Base translations (EN/PT) for common UI strings: buttons, form labels, dialog text, navigation, theme.
@@ -195,6 +420,107 @@ Base translations (EN/PT) for common UI strings: buttons, form labels, dialog te
 - Sonner for toast notifications
 - Lucide + Tabler icons
 
+## The bento layer
+
+Turing grew a second era of chrome — the frosted tile, the airy hero, the
+mosaic — inside one product while this package sat next to it exporting console
+chrome. It lives here now: the components, their stylesheet, their strings and
+their suites. Turing consumes them through one-line re-exports at the paths its
+pages already imported, so a product adopting the layer writes the imports above
+rather than a second copy.
+
+What stayed behind is the product's, deliberately: commercial chrome (activation,
+quota, the first-run tour) and navigation data. `BentoListPage` takes a `layout`
+object rather than fetching one, because where a layout is stored is the
+product's business — its API, its cache, its mutation library.
+
+It is a separate entry point, so a console still on the first era carries none
+of it:
+
+```ts
+import "@viglet/viglet-design-system/bento.css";
+import {
+  BentoEntityShell,
+  BentoListPage,
+  BentoFormHero,
+  BentoNavRail,
+  BentoCommandPalette,
+} from "@viglet/viglet-design-system/bento";
+```
+
+The stylesheet is a separate import from the components, so a consumer taking
+only the layout maths does not pull CSS it never renders. It reads the preset's
+tokens, so import the preset too.
+
+"Carries none of it" is measured rather than claimed. `pnpm run build` ends by
+bundling three fixtures through this package's own `exports` map, and fails if a
+bento module, a bento class name or a run of `bento.css`'s selectors reaches a
+consumer that imported only the root entry. `size-budget.json` records what each
+entry costs: today the whole root entry is 87 KB gzipped and `./bento` 22 KB,
+measured with everything the build externalises left out, so the numbers
+describe this package rather than its dependencies. The preset's
+`--vg-bento-tone-*` tokens are deliberately not counted as the layer: they ship
+with every other token and are about a kilobyte of custom properties.
+
+The test is whether a root consumer carries the subpath's **code**, not whether
+the subpath exists. `./floating-formulas-bg` has its own entry *and*
+`FloatingFormulasBg` is exported from the root barrel, where `Login` and
+`StartupFirst` render it — so its rules are in `./styles` too, and that is
+correct rather than a leak. The subpath is for a consumer who wants only that
+background.
+
+Every subpath in the table above is also **imported, required and type-checked
+as you would use it** on each build: one fixture pulls all fifteen through the
+real `exports` map, a CommonJS probe requires the seven that offer it, and a
+generated TypeScript probe imports a value from each typed entry and uses it —
+so a `types` field resolving to the wrong declarations fails here rather than
+turning into `any` in your editor.
+
+That last check found a real one. `"type": "module"` makes Node read any `.js`
+as ESM, and the CommonJS entries were named `<entry>.cjs.js`, so every
+`require()` of this package failed. They are `<entry>.cjs` now. No product met
+it, because every consumer — the Vite ones through their bundler, the Next ones
+through the App Router — takes the `import` condition.
+
+**`./bento` requires `react-router-dom`.** The package declares that peer
+optional because the root entry does not need it — only `./router` and `./bento`
+do, and npm cannot mark a peer required for one entry point and optional for
+another. `pnpm run build` fails if any other entry starts importing it, so the
+split above stays true rather than becoming folklore.
+
+[docs/BENTO-AUTHORING.md](docs/BENTO-AUTHORING.md) is the contract for writing a
+bento page: the three page shapes, what the package will not hold for you, and
+the colour, i18n, accessibility and layout rules that keep two consoles looking
+like the same product. Read it before the first screen, not after the fifth.
+
+[docs/BENTO-BOUNDARY.md](docs/BENTO-BOUNDARY.md) says which exports become part
+of this package and which stay in the product, and why. Four of them are one
+product's commercial offer rendered as cards, and shipping those as chrome would
+put that offer in every console.
+
+## Contributing
+
+The package manager here is pnpm, matching the Shio, Turing, Dumont, Cloud Home
+and Schools workspaces. The Cloud Console installs with npm, which is a fact
+about that repository and not about this one.
+
+```bash
+pnpm install
+pnpm lint         # eslint
+pnpm typecheck    # tsc -b --force
+pnpm test         # vitest
+pnpm build        # tsc, vite, and the dist checks
+pnpm storybook    # the component catalogue, on :6006
+```
+
+CI runs all of those on every push and pull request, and the publish workflow
+re-runs them before it releases.
+
+`pnpm build` ends in `scripts/check-dist.mjs`, which fails the build when dist
+would be broken for consumers in a way nothing here can see — a declaration
+importing through a `node_modules` path, a test artefact in the published tree,
+or an `exports` entry the build did not produce.
+
 ## License
 
 Apache-2.0

package/dist/assets.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./products-DL_YYXkV.cjs");exports.dumontLogoUrl=e.n,exports.productLogos=e.t,exports.shioLogoUrl=e.r,exports.turingLogoUrl=e.i,exports.vigletLogoUrl=e.a;

package/dist/assets.es.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, r, t as i } from "./products-Du9KB6Xl.js";
+export { n as dumontLogoUrl, i as productLogos, r as shioLogoUrl, t as turingLogoUrl, e as vigletLogoUrl };