@inntechcorp/it-design 4.0.0-beta.1 → 4.0.0-beta.11

package/ACCESSIBILITY.md

@@ -19,7 +19,7 @@ ITD Design System, **WCAG 2.1 AA** standartlarına uygun olarak geliştirilmişt
 Tüm ITD form bileşenleri aşağıdaki WCAG standartlarını karşılar:
 
 | Component | HTML Element | ARIA Attributes | Screen Reader | Keyboard | WCAG Level |
-|-----------|--------------|-----------------|---------------|----------|------------|
+| --------- | ------------ | --------------- | ------------- | -------- | ---------- |
 | Input     | `<input>`    | ✅ Full         | ✅ Full       | ✅ Full  | AA         |
 | Textarea  | `<textarea>` | ✅ Full         | ✅ Full       | ✅ Full  | AA         |
 | Checkbox  | `<input>`    | ✅ Full         | ✅ Full       | ✅ Full  | AA         |
@@ -33,15 +33,17 @@ Tüm ITD form bileşenleri aşağıdaki WCAG standartlarını karşılar:
 Her form elementi uygun ARIA attribute'larını içerir:
 
 **Genel (tüm form elementleri):**
+
 ```tsx
 <input
   id="input-123"
-  aria-invalid="true"                    // Error varsa
-  aria-describedby="input-123__error"    // Error mesajına bağlantı
+  aria-invalid="true" // Error varsa
+  aria-describedby="input-123__error" // Error mesajına bağlantı
 />
 ```
 
 **Select (Combobox pattern):**
+
 ```tsx
 <input
   role="combobox"                        // Combo box elementi
@@ -54,12 +56,12 @@ Her form elementi uygun ARIA attribute'larını içerir:
   aria-describedby="select-123__error"   // Error mesajı
 />
 
-<div 
+<div
   id="select-123-listbox"                // ← aria-controls buraya bağlı
   role="listbox"                         // Listbox elementi
   aria-multiselectable="true"            // Multi select mi
 >
-  <div 
+  <div
     id="select-123-option-2"             // ← aria-activedescendant buraya bağlı
     role="option"                        // Option elementi
     aria-selected="true"                 // Seçili mi
@@ -71,6 +73,7 @@ Her form elementi uygun ARIA attribute'larını içerir:
 ```
 
 **Screen Reader deneyimi:**
+
 1. Tab → "Combo box, collapsed, type to filter"
 2. Enter → "Expanded, listbox with 5 options"
 3. Arrow Down → "Seçenek 1, option 1 of 5"
@@ -88,7 +91,7 @@ ITD, WCAG'ın önerdiği **dual announcement** pattern'ini kullanır:
 </ErrorTooltip>
 
 // 2. Hidden Announcement (screen reader kullanıcıları için)
-<p 
+<p
   id="input-123__error"
   role="alert"
   aria-live="assertive"
@@ -99,6 +102,7 @@ ITD, WCAG'ın önerdiği **dual announcement** pattern'ini kullanır:
 ```
 
 **Avantajlar:**
+
 - 👁️ Görsel kullanıcılar → Hover'da tooltip görür
 - 🔊 Screen reader → Error anında bildirim alır
 - 🎯 Duplicate announcement yok
@@ -109,18 +113,19 @@ ITD, WCAG'ın önerdiği **dual announcement** pattern'ini kullanır:
 
 ### Genel Klavye Desteği
 
-| Tuş | Davranış |
-|-----|----------|
-| `Tab` | Sonraki focusable elemente git |
-| `Shift + Tab` | Önceki focusable elemente git |
-| `Enter` | Button/Link aktive et, Form submit |
-| `Space` | Button/Checkbox/Switch aktive et |
-| `Escape` | Modal/Dropdown kapat |
-| `Arrow Keys` | Select/DatePicker navigasyonu |
+| Tuş           | Davranış                           |
+| ------------- | ---------------------------------- |
+| `Tab`         | Sonraki focusable elemente git     |
+| `Shift + Tab` | Önceki focusable elemente git      |
+| `Enter`       | Button/Link aktive et, Form submit |
+| `Space`       | Button/Checkbox/Switch aktive et   |
+| `Escape`      | Modal/Dropdown kapat               |
+| `Arrow Keys`  | Select/DatePicker navigasyonu      |
 
 ### Component-Specific
 
 **Select:**
+
 - `Arrow Down/Up` → Dropdown açar/seçenekler arası geçiş
 - `Enter` → Seçim yapar, dropdown kapatır
 - `Escape` → Dropdown kapatır
@@ -143,13 +148,13 @@ ITD Select, [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns
 />
 
 // Dropdown (Listbox)
-<div 
+<div
   id="select-id-listbox"                 // Input'tan referans ediliyor
   role="listbox"                         // Listbox elementi
   aria-multiselectable="true"            // Multi-select desteği
 >
   // Options
-  <div 
+  <div
     id="select-id-option-2"              // aria-activedescendant buraya işaret edebilir
     role="option"                        // Option elementi
     aria-selected="true"                 // Seçili mi
@@ -162,27 +167,29 @@ ITD Select, [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns
 
 **Radix UI Select ile karşılaştırma:**
 
-| ARIA Attribute | Radix UI | ITD | Notlar |
-|----------------|----------|-----|--------|
-| `role="combobox"` | ✅ | ✅ | Her ikisi de tam uyumlu |
-| `aria-controls` | ✅ | ✅ | Listbox'a bağlantı |
-| `aria-expanded` | ✅ | ✅ | Açık/kapalı durumu |
-| `aria-haspopup` | ✅ | ✅ | Popup tipi belirtimi |
-| `aria-autocomplete` | ✅ | ✅ | ITD: showSearch prop'una göre |
-| `aria-activedescendant` | ✅ | ✅ | Aktif option tracking |
-| `aria-invalid` | ❌ | ✅ | **ITD avantajı** |
-| `aria-describedby` | ❌ | ✅ | **ITD avantajı** |
-| Error announcement | ❌ | ✅ | **ITD avantajı** |
+| ARIA Attribute          | Radix UI | ITD | Notlar                        |
+| ----------------------- | -------- | --- | ----------------------------- |
+| `role="combobox"`       | ✅       | ✅  | Her ikisi de tam uyumlu       |
+| `aria-controls`         | ✅       | ✅  | Listbox'a bağlantı            |
+| `aria-expanded`         | ✅       | ✅  | Açık/kapalı durumu            |
+| `aria-haspopup`         | ✅       | ✅  | Popup tipi belirtimi          |
+| `aria-autocomplete`     | ✅       | ✅  | ITD: showSearch prop'una göre |
+| `aria-activedescendant` | ✅       | ✅  | Aktif option tracking         |
+| `aria-invalid`          | ❌       | ✅  | **ITD avantajı**              |
+| `aria-describedby`      | ❌       | ✅  | **ITD avantajı**              |
+| Error announcement      | ❌       | ✅  | **ITD avantajı**              |
 
 **Sonuç:** ITD Select, Radix UI ile aynı seviyede ARIA desteği sağlar, hatta error handling konusunda daha kapsamlıdır.
 
 **DatePicker:**
+
 - `Arrow Keys` → Tarih navigasyonu
 - `Home/End` → Ay başı/sonu
 - `Page Up/Down` → Önceki/sonraki ay
 - `Enter` → Tarih seçer
 
 **Modal:**
+
 - `Escape` → Modal kapatır
 - `Tab` → Modal içinde focus trap (dışarı çıkmaz)
 
@@ -211,17 +218,17 @@ pointer-events: none  // Child elementlerde
 
 ### ARIA Roles
 
-| Component | Role | States & Properties |
-|-----------|------|---------------------|
-| Button    | `button` | `aria-disabled`, `aria-pressed` (toggle) |
-| Checkbox  | `checkbox` | `aria-checked`, `aria-invalid`, `aria-describedby` |
-| Switch    | `switch` | `aria-checked`, `aria-invalid`, `aria-describedby` |
-| Radio     | `radio` | `aria-checked`, `aria-invalid` |
-| Select (Input) | `combobox` | `aria-controls`, `aria-expanded`, `aria-haspopup`, `aria-autocomplete`, `aria-activedescendant`, `aria-invalid`, `aria-describedby` |
-| Select (Dropdown) | `listbox` | `aria-multiselectable` |
-| Select (Option) | `option` | `aria-selected`, `aria-disabled` |
-| Modal     | `dialog` | `aria-modal`, `aria-labelledby`, `aria-describedby` |
-| Alert     | `alert` | `aria-live` (implicit) |
+| Component         | Role       | States & Properties                                                                                                                 |
+| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Button            | `button`   | `aria-disabled`, `aria-pressed` (toggle)                                                                                            |
+| Checkbox          | `checkbox` | `aria-checked`, `aria-invalid`, `aria-describedby`                                                                                  |
+| Switch            | `switch`   | `aria-checked`, `aria-invalid`, `aria-describedby`                                                                                  |
+| Radio             | `radio`    | `aria-checked`, `aria-invalid`                                                                                                      |
+| Select (Input)    | `combobox` | `aria-controls`, `aria-expanded`, `aria-haspopup`, `aria-autocomplete`, `aria-activedescendant`, `aria-invalid`, `aria-describedby` |
+| Select (Dropdown) | `listbox`  | `aria-multiselectable`                                                                                                              |
+| Select (Option)   | `option`   | `aria-selected`, `aria-disabled`                                                                                                    |
+| Modal             | `dialog`   | `aria-modal`, `aria-labelledby`, `aria-describedby`                                                                                 |
+| Alert             | `alert`    | `aria-live` (implicit)                                                                                                              |
 
 ### Live Regions
 
@@ -257,8 +264,8 @@ ITD, **mouse** ve **keyboard** focus'unu ayırır:
 ### Focus Ring Colors
 
 ```css
---itd-ring: oklch(0.62 0.18 250);  /* Light tema */
---itd-ring: oklch(0.72 0.20 250);  /* Dark tema */
+--itd-ring: oklch(0.62 0.18 250); /* Light tema */
+--itd-ring: oklch(0.72 0.2 250); /* Dark tema */
 ```
 
 ### Skip Link
@@ -297,14 +304,14 @@ Klavye kullanıcıları için ana içeriğe atlama linki:
 
 ```css
 /* Light Theme */
---itd-text: oklch(0.35 0.02 250);      /* Kontrast: 11:1 */
+--itd-text: oklch(0.35 0.02 250); /* Kontrast: 11:1 */
 --itd-text-muted: oklch(0.55 0.02 250); /* Kontrast: 5.5:1 */
---itd-border: oklch(0.85 0.01 250);     /* Kontrast: 2.8:1 */
+--itd-border: oklch(0.85 0.01 250); /* Kontrast: 2.8:1 */
 
 /* Dark Theme */
---itd-text: oklch(0.85 0.02 250);      /* Kontrast: 10:1 */
+--itd-text: oklch(0.85 0.02 250); /* Kontrast: 10:1 */
 --itd-text-muted: oklch(0.65 0.02 250); /* Kontrast: 6:1 */
---itd-border: oklch(0.30 0.01 250);     /* Kontrast: 3.5:1 */
+--itd-border: oklch(0.3 0.01 250); /* Kontrast: 3.5:1 */
 ```
 
 ### High Contrast Mode
@@ -339,8 +346,8 @@ Kullanıcının hareket tercihine saygı gösterilir:
 
 ```css
 @media (prefers-reduced-motion: reduce) {
-  .modal-enter-active,
-  .modal-exit-active,
+  .itd-modal-transition-enter-active,
+  .itd-modal-transition-exit-active,
   .itd-select-dropdown-transition-enter-active,
   .itd-select-dropdown-transition-exit-active,
   .datepicker-modal-enter-active,
@@ -469,16 +476,16 @@ Cmd + F5
 ### Otomatik Test Scripti
 
 ```tsx
-import { render } from '@testing-library/react'
-import { axe, toHaveNoViolations } from 'jest-axe'
+import { render } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'jest-axe';
 
-expect.extend(toHaveNoViolations)
+expect.extend(toHaveNoViolations);
 
 it('should not have accessibility violations', async () => {
-  const { container } = render(<YourComponent />)
-  const results = await axe(container)
-  expect(results).toHaveNoViolations()
-})
+  const { container } = render(<YourComponent />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
 ```
 
 ---
@@ -507,6 +514,7 @@ Accessibility sorunları bulursanız:
 ITD Design System - Accessibility features are part of the core library.
 
 **Standartlar:**
+
 - WCAG 2.1 (W3C)
 - ARIA 1.2 (W3C)
 - Section 508 (US Federal)
@@ -514,4 +522,3 @@ ITD Design System - Accessibility features are part of the core library.
 ---
 
 _Son güncelleme: Kasım 2024_
-

package/CHANGELOG.md

@@ -0,0 +1,304 @@
+# Changelog
+
+What changed between two builds, without reading git log. The log starts at
+`4.0.0-beta.3`; earlier v4 history lives in git and [MIGRATION.md](MIGRATION.md)
+carries the v3 to v4 story. Convention from here on: every version bump adds
+its entry at the top, grouped as **Breaking / Added / Fixed**, one line per
+change, written for the consumer (what they see, not which file moved).
+
+## 4.0.0-beta.11 (2026-09-04)
+
+### Added
+
+- **Query blocks can be used.** Fifteen manifest blocks drew controls that
+  reached nothing: category chips, the provider filter, grid search,
+  pagination, tournament cards, the help rail, promotion cards, jackpot game
+  tiles. Changing a block's own question is not an `onAction` - the host has
+  to re-ask - so the page context gains
+  `onQueryChange({ id, component, platform, change })`, editor-gated like
+  `onAction`, and the answer gains `query` (the echo that makes a control
+  controlled), `paging` (total/hasMore/loadingMore + named sub-lists) and
+  `allCategoryId`. Leave the echo out and every control stays exactly as
+  uncontrolled as it is today.
+- `tournament` joins the action union beside `promotion`; a winner row can
+  carry the `slug` of the game it was won on (both winner surfaces open it);
+  `PageQueryResult.promotions` is a typed channel (`extra.promotions` still
+  works); `PageLabels.empty`.
+- **Every page-block link rides the router seam** (BlockLink): banners and
+  slider slides, layout box tiles, the featured lead, the carousel's ALL, the
+  casino band's tiles, the mobile back arrow, promotion cards. With a router
+  adapter wired a plain click reaches the host; with none it is today's
+  anchor. `BlockLink` now exports from the barrel.
+- `GameBox.reserveRatio` - the shape a tile holds when nothing else decides.
+
+### Fixed
+
+- **A GameBox could end up with no shape at all, collapsing its whole row.**
+  `useNaturalRatio` read the picture's dimensions from a frame loop that the
+  picture's own `load` event cancelled, so a cached image (the common case,
+  and certain on reload) left the ratio null for ever. The hook now looks
+  once synchronously before it starts watching, takes a selector so a broken
+  tile cannot adopt its placeholder's aspect, and layout boxes reserve
+  production's own design shapes until their visual lands.
+- **`{ games: [] }` shimmered for ever.** Blocks tested a list's length, so
+  an empty answer and a missing one were the same state; they now split, and
+  an empty answer draws the site's not-found panel inside the same markers.
+- **Demo play launched the real game.** The page layer forwarded GameBox's
+  `onPlay(slug, fun)` with an arity-0 arrow that dropped the flag, and three
+  copies of the open lambda were pinned to `is_fun: false`.
+- **The phone painted a background image the site never shows.** Production
+  keeps every `background-image` under `html[platform="desktop"]` and the
+  colour outside it; the renderer now passes the PAGE's platform, and a
+  mobile page's form stops asking for a visual.
+- **Promotion cards navigated the editor away from the page being designed** -
+  the one page href that never passed through the action gate.
+
+## 4.0.0-beta.10 (2026-09-03)
+
+### Added
+
+- **Every site block's link rides the router seam.** Footer (socials, store
+  badges, seal logos), MobileBottomNav tabs, MegaMenu rows and the Header's
+  profile-menu rows (which ignored `href` and rendered buttons) now render
+  through ITDLink, so a wired router adapter handles plain clicks - no more
+  site-side click shims. The anchors' own class/target/aria-current output
+  is unchanged; rows without an href render today's button/anchor.
+- **ITDLink treats external URLs as the browser's**: a scheme'd or
+  protocol-relative `to` gets no adapter href mapping, no host Link, no
+  interception and no active match (an adapter could previously pushState
+  "https://..."). `_blank` links get `rel="noopener"` unless a rel is given.
+- **MegaMenu `loading`/`skeletonCount`** (default ten card-shaped rows, like
+  MobileBottomNav's), `MegaMenuLink`/entry `label` widened to ReactNode, and
+  `target`/`rel` on rows.
+
+### Fixed
+
+- MegaMenu drawer: a closed drawer forgets which accordions were opened -
+  the state lives above the unmounted subtree, so it now resets when the
+  exit animation finishes (production's old unmount semantics).
+
+## 4.0.0-beta.9 (2026-09-03)
+
+### Added
+
+- **MegaMenu drawer mode**: a controlled `open` prop mounts production's
+  full-screen frame - the fixed scroll-container wrapper (its `::before` is
+  the backdrop wash), the right-to-left slide (0.25s, production easings,
+  travel as a CSS var), scroll lock in the menu's own realm, Escape close
+  (`onOpenChange`/`closeOnEscape`), and a top offset that clears the mobile
+  header plus the announcement bar and RIDES its scroll-away
+  (`--itd-mobile-header-h` + the announcement vars). `open` unset renders
+  today's bare nav byte-identically. Group entries gain `label`/`icon`: a
+  named group draws production's STATIC `open-group` head over always-visible
+  items (a named-and-collapsible group stays the `accordion` kind).
+- **Header user surface**: `HeaderUser.avatar` (tri-state: unset keeps
+  today's stand-in art; a URL renders the photo with bar + popover falling
+  to the DefaultAvatar silhouette TOGETHER on load error; `null` opts into
+  the silhouette outright), `HeaderUser.currency` (threads into `Amount`;
+  unset keeps the TRY default), `HeaderUser.balanceLoading` (a
+  width-reserved skeleton in the balance slot, no eye toggle - production's
+  pre-fetch window), `logoHref` (the logo becomes a real ITDLink: native
+  middle/modifier clicks, client-side navigation only with a router
+  adapter), and `HeaderNavItem.target`/`rel` - nav rows render through
+  ITDLink for app paths while scheme'd/protocol-relative URLs stay plain
+  anchors (never handed to the adapter) with `noopener` auto-added on
+  `_blank`.
+
+### Fixed
+
+- The `blocks/mega-menu` type stub shipped broken in beta.7/beta.8: the
+  stub generator's regex swallowed the two barrel statements between two
+  block exports, leaking `AnnouncementBar` re-exports (with unresolvable
+  paths) and a phantom `default` into it - subpath imports of mega-menu
+  type-errored while the runtime ESM stayed correct. The parse is now
+  brace-bounded, the generator refuses unparseable specs, and pack-smoke
+  compiles ALL 38 stubs instead of sampling two.
+
+## 4.0.0-beta.8 (2026-09-02)
+
+### Added
+
+- The site-theme contract is public API: the `SitePreset` type,
+  `resolveSitePresetOverrides`, `validateSitePreset`, and `EXAMPLE_SITE`
+  (the tuned, regression-locked classic navy palette a migrating site
+  adopts as its default preset) all export from the barrel.
+- The `multipleOf` form validator actually ships: `MULTIPLE_OF` enum
+  member, step check (zero/negatives refused), optional `currency` on the
+  rule for the stock message, en/tr locale strings. Ported from v3.1.22 -
+  the beta.4 notes listed it by mistake; it had never left the v3 line.
+
+### Docs
+
+- THEMING.md consumer pitfall: old postcss-calc/cssnano print a harmless
+  "Lexical error" flood on `global.css`'s OKLCH channel math when Vite runs
+  package CSS through the consumer's postcss config - upgrade to cssnano 9 /
+  postcss-calc 11, or set `preset: ['default', { calc: false }]`.
+
+## 4.0.0-beta.7 (2026-09-02)
+
+### Added
+
+- Per-block subpath exports: `@inntechcorp/it-design/blocks/<name>` now
+  resolves (types + ESM + CJS) for all 38 blocks, so sites keep per-block
+  lazy chunks instead of pulling the barrel. Raw `dist/es/...` paths remain
+  unexported. Subpath types are generated stubs that re-export from the
+  bundled `index.d.ts` - identical types, no duplication.
+- The auth blocks joined the public API: `LoginPanel`, `SignupPanel`
+  (+ `stepOf`/`deriveSteps`), `CompletionPanel`, `AuthPage` (+
+  `ForceChangePassword`, `ResetPassword`, `EmailVerification`) and their
+  prop/text types export from the barrel and from `./blocks/*` subpaths.
+
+### Added (site marker parity)
+
+- The missing `inn-*` markers came back (contract rule 2): back-to-top's
+  container, the game-box empty-tile skeleton pair, the slider slide
+  spinner (platform-flavored, on the page-composed Banner slides), the
+  mobile mega-menu group/item/icon/sub-item set, the slider slide-number,
+  and the hub's `inn-statistics-summary`. GameBox gains `emptyArt` (the
+  site's per-category placeholder art URL) drawing the
+  `inn-(mobile-)image-box-empty-image` layer in the skeleton tile and over
+  a loading/broken art box. The seven `inn-(mobile-)user-enter-*` markers
+  live in site-composed hub slot content and stay on the site side.
+- Legacy tenant-CSS aliases: the site's un-prefixed stable class names now
+  ride alongside the `itd-*` ones - 44 `tournament-*` names in the
+  tournaments block, `header-separator`/`header-menu-list`/
+  `header-menu-item` in the header, and the `winners-*` set in the
+  casino-featured winners box. Tenant custom CSS written against the old
+  names keeps working through the v4 swap.
+
+### Changed
+
+- SignupPanel: a `readonly` field now renders its REAL control disabled
+  (a locked Select showing the value, a locked Input otherwise) instead of
+  the label-value fact row; `.itd-signup-fact` is gone. Submit payloads are
+  unchanged. The step/section title wears the shell's title treatment
+  (16px semibold with breathing room) and hints inside signup align left.
+
+## 4.0.0-beta.6 (2026-09-02)
+
+### Breaking
+
+- `lucide-react` resolves at `^1.39.0` (was `^0.562.0`, the dead-ended final
+  0.x). Every icon name the library ships survives in 1.x, including the
+  deprecated aliases; apps importing `lucide-react` directly should bump to
+  `^1` to dedupe, and lucide 1.x dropped ALL brand icons (Facebook/Instagram/
+  Twitter/Github/...) permanently - see MIGRATION.md section 10.
+
+### Fixed
+
+- Publish/build log noise silenced: the postcss-calc "Lexical error" flood
+  (the plugin could not parse OKLCH channel math and folded nothing) and the
+  bundler's "use client" directive warnings are gone; caniuse-lite refreshed.
+
+### Internal
+
+- Dependency refresh: consumers' install shrinks (`react-nanny` removed -
+  it was never imported), and the toolchain moves up - cssnano 9 (native
+  relative-color understanding), postcss-import 17 / postcss-nesting 14 /
+  postcss-preset-env 11, storybook 10.5, vitest 4.1.11, playwright 1.62,
+  jsdom 30, jest-dom 7, i18next 26 + react-i18next 17, rollup 4.63,
+  rollup-plugin-typescript2 0.37 (defuses the picomatch 2.3.2 glob break),
+  rollup-plugin-dts 6.5. Deliberately NOT taken: Babel 8, Vite 8 and
+  TypeScript 7 (ecosystem support for our build chain is not there yet).
+  Unused devDeps dropped: rollup-plugin-styles, tslib, postcss-calc,
+  postcss-custom-properties, @storybook/builder-vite,
+  @testing-library/user-event, eslint-plugin-storybook (+ the orphan
+  .eslintrc.json and the stale jackspeak resolution pin).
+
+## 4.0.0-beta.5 (2026-09-02)
+
+### Added
+
+- **CompletionPanel**: the forced post-login step (login-method migration's
+  front door). Eyebrow chip, hint, site-composed fields inside the panel's
+  form, and the grace/forced split: skip + deadline while `skippable`, the
+  forced sentence after.
+- **HubSecurity**: the hub's Sign-in & security screen - its own Ayarlar
+  tab with identity/method rows, state badges and one action per row; the
+  list wears the hub row surface via `--itd-hub-security-bg` (falls back to
+  `--site-hub-security-bg`, then the shared balance-row token).
+- **SignupPanel**: the registration ENGINE from the auth design canvas. The
+  panel takes the brand's field table (name/kind/required/step/options,
+  readonly facts, collapsed reveals, password confirm twins, the
+  auto-suggested nickname) and derives the screens itself: identity →
+  verify → credentials → profile, rendered as one form (`layout="single"`),
+  one step at a time (`layout="steps"`, site-controlled `step` with chip
+  progress), or with the code inside the form
+  (`verificationTiming="in_form"` - cells unlock when required fields are
+  filled and the code rides the payload). Wears the login shell.
+- **LoginPanel v2** (the auth design canvas, additively): multi-identity
+  tabs (`identifiers` + per-identifier labels/placeholders), alternate
+  methods under an OR divider (`alternates`/`onAlternate`), the magic-link
+  waiting room (`step="link-sent"`), a passkey variant (`variant="passkey"`),
+  the password-fallback identity row (allow_password + `username` shows
+  the identifier as a fact with a change action), and the create-account
+  footer (`newHere`/`createAccount`/`onCreateAccount`) on the screens a new
+  visitor can land on. Sites passing yesterday's props render yesterday's
+  panel.
+
+### Fixed
+
+- Opening a standalone Sheet no longer jumps a scrolled page to the top.
+  Every sheet now runs non-modal and holds the library's own scroll lock
+  (root `overflowY: hidden` + gutter compensation) instead of Vaul's
+  body `position: fixed`; the sheet also traps its own focus, on both the
+  standalone and embedded paths.
+
+## 4.0.0-beta.4 (2026-08-18)
+
+### Breaking
+
+- The stock DARK theme now seeds from the Neutral preset (true grey), matching
+  light. It was Slate (blue-tinted) by accident of history; pass
+  `surfaceBase` with the Slate preset value to keep the old look.
+- `useITD().brokenImage` / `changeBrokenImage` removed. Dead since v3.1.5;
+  Image renders its own broken state (`brokenWidth`/`brokenHeight`).
+
+### Added
+
+- **LineChart**: themed chart layer over recharts. Series colors come from
+  `--itd-chart-series-*` tokens (semantic fallbacks: primary/success/error/
+  neutral), grid/ticks/tooltip/legend are DS surfaces, tokens are read
+  realm-aware from the chart's own document. `formatTooltipTitle(value, row)`
+  formats the tooltip title separately from the axis tick (falls back to
+  `formatXTick`). `mobile="expand"` swaps the chart for a tappable POSTER
+  on touch devices (dimmed preview + centered "open chart" button); tapping
+  opens a fullscreen fake-landscape viewer (CSS-rotated while portrait, with
+  a self-fading "rotate your phone" coach mark) panned by native horizontal
+  scroll, closed top-right - a pure view: filters and range pickers stay on
+  the page.
+- **StatCard**: the back-office summary box. Amount value with count-up,
+  trend arrows or a custom glyph, info Popover (desktop) / bottom Sheet
+  (touch), multi-value mode where the labels switch the value, widths
+  reserved up front so the counter never resizes the box. Info popover width
+  overridable via `--itd-stat-card-info-max-width`.
+- **Table sorting**: `sortable` on table/columns, controlled or uncontrolled
+  `sort`, client and `server` modes, locale-aware natural comparison, 3-state
+  cycle (asc / desc / off), `sortValue`/`sorter` escape hatches.
+- **Table expansion**: rows identified by stable paths, controlled
+  `expandedKeys`, `loading` (spinner keeps rows in place, `inert` below) and
+  `emptyContent`, horizontal scroll with a keyboard-reachable scroller.
+- **Badge override tokens**: `--itd-badge-text`, `--itd-badge-font-weight`
+  (the code-input instance-override pattern).
+- `accentHeader` on Table; `overflow` on Tabs; `multipleOf` form validator.
+- **COMPONENTS.md** (export to file to one-sentence index) and a THEMING.md
+  "Consumer pitfalls" section.
+
+### Fixed
+
+- dist `.d.ts` no longer collapses 11 optional props to `undefined` (the
+  ghost "string is not assignable to undefined" consumer errors) - a paths
+  mapping poisoned declaration emit; pack-smoke now guards the bundle.
+- `locked` no longer leaks to the DOM from Form.Control/Form.Item injection
+  (the React warning every form logged once per page).
+- Alert keeps ALL loose children: interpolations like `Count: {n}` no longer
+  lose everything after the first text node, `{0}` renders, and an element
+  inside running text is content, not the icon.
+- Inputs no longer lock up when `autoComplete` is unset; jackpot strip
+  arrows and fade restored; button padding ramp rejoined the size scale
+  (8/12/12/16/16/20); dead token scale removed.
+- Global `a:hover` underline removed - the underline belongs to the link
+  variant. Table headers read as text at one type step below their cells.
+- StatCard: currency values weigh semibold like the row; the selected
+  multi-mode label uses the theme's selected-item ink (brighter than hover
+  on dark).