@gouno/ui 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+### Added
+- Core locale-only ConfigProvider, English and Simplified Chinese packs, and typed local copy overrides for Input, DatePicker, InputNumber, Select, Upload and Pagination.
+
+### Fixed
+- Select clear and tag-removal keyboard actions, focus return, generated listbox IDs and searchable active-descendant ownership.
+- Input suffix/clear spacing and Pagination ReactNode navigation labels.
+- Showcase Fixture controls reserve tooling space instead of covering product actions; standalone page navigation starts collapsed.
+
+### Changed
+- Participating controls use English fallback consistently. Configure zhCN to retain Chinese defaults; existing explicit text remains authoritative. See [migration](docs/component-localization.md).
+- Review completion retains scope/evidence and can reopen after a defect instead of requiring every catalog entry to remain permanently at 100.
+
+## [0.3.2] - 2026-09-13
+
+### Fixed
+
+- Fixed the tag-driven npm release workflow to publish the generated local tarball path correctly, preserving npm provenance and Trusted Publishing support.
+
+## [0.3.1] - 2026-09-13
+
+### Added
+
+- Added standard public npm distribution metadata for `@gouno/ui`, including immutable registry release metadata and the MIT license.
+- Added package-surface validation through `package:check` and `release:check`, with CI release gates covering the published entry points and archive contents.
+- Added tag-driven npm publishing with npm provenance / Trusted Publishing support and GitHub Release artifact creation.
+- Added release documentation describing immutable versions, exact release identity, npm authentication and consumer upgrades.
+
+
+## [0.3.0] - 2026-09-12
+
+### Changed
+
+- Other 6F3: hardened Core `Affix` as a standard top-sticky container and `BackTop` as a window-scroll threshold control with real visibility behavior, caller-owned accessible copy, cancellable smooth-scroll action, standard DOM/event/ref passthrough, same-source Showcase examples, and focused regressions.
+- Other 6F2: hardened Core `Watermark` with caller-owned required content, XML-safe SVG text encoding, normalized tile/rotation/opacity inputs, and standard div DOM/ARIA/style/ref passthrough. Core no longer injects the Gouno brand into generic watermarks.
+- Other 6F1: hardened Core `FloatButton` as a generic icon-only floating action with caller-owned icon/accessibility copy, real button-or-anchor semantics, standard DOM/event/ref passthrough, working ReactNode Tooltip rendering, and explicit disabled-link behavior. The BackTop-style default arrow and string-only pseudo-tooltip bridge are removed from the generic action contract.
+- Feedback 6E4: hardened Core `Tour` as a controlled modal walkthrough with caller-owned navigation copy, a controlled/uncontrolled normalized step index, canonical Dialog focus containment/Escape close/focus return, and visible step titles as the dialog accessible name. The never-implemented `TourStep.target` hook and injected English `Product tour` / `Previous` / `Next` / `Finish` copy are removed; target highlighting/positioning and product onboarding orchestration remain outside Core.
+- Feedback 6E3: hardened Core `NotificationProvider` as a finite-lived local notification queue. Provider-local monotonic IDs replace time/random keys, removal timers are tracked and cleared on unmount, and each notice owns one atomic `status` region instead of nesting under an additional outer `aria-live`. `NotificationNotice` is now an explicit public type; notice duration accepts finite positive milliseconds and otherwise falls back to 4500ms, removing the old `duration=0` uncloseable-persistence sentinel. Persistent notification centers, read state, manual close/update/destroy, and cross-root singleton behavior remain product-owned.
+- Feedback 6E2: hardened Core `MessageProvider` as a local transient queue. Message IDs are now deterministic per Provider, removal timers are tracked and cleared on unmount, and each message owns its `status`/`alert` live-region semantics instead of stacking those roles under a second outer `aria-live`. The existing `open/info/success/warning/error` hook surface is retained, `duration` only controls automatic removal, and global singleton, manual key/update/destroy, Promise orchestration, and product notification-center behavior remain out of Core.
+- Feedback 6E1: hardened Core `Popconfirm` around one local confirmation lifecycle. Confirmation and cancellation labels are now explicitly caller-owned with no injected English defaults; the trigger child is no longer cloned or overwritten, while the wrapper composes natural bubbling and lets child/root `preventDefault` veto opening. Async confirmation exposes `aria-busy`, locks cancellation/Escape while pending, closes on success, and preserves context after rejection. Standard span DOM/ref ownership is retained without adding controlled-open, permission, MFA, or product feedback orchestration.
+- Data Entry 6D7: hardened Core `TreeSelect` around its actual native-select implementation. Hierarchical data is now readonly, `title` is explicitly string text instead of a ReactNode that could stringify to `[object Object]`, single/multiple values retain native selection semantics, placeholder copy is caller-owned, hierarchy indentation is non-verbal whitespace, and the component now forwards the real select ref with canonical size/status, disabled and standard DOM/form/ARIA ownership. Search, async tree loading, checkbox selection, popup-tree behavior and custom node rendering remain out of scope.
+- Data Entry 6D6: hardened Core `Cascader` while preserving its native per-level select architecture. `value/defaultValue/onChange` now form one path-state contract, clearing a level truncates the path instead of storing an empty key, root naming is caller-owned through standard group ARIA, and each native select uses a language-neutral numeric level name. English `Please select` / `Select` / `Level N` defaults were removed; placeholder copy is caller-owned. The component now supports readonly option trees, canonical control sizing/status, disabled semantics, stable slots and a real root ref without adding search, async loading or custom-panel feature bags.
+- Data Entry 6D5: hardened Core `Transfer` around one target-key state contract with stable item keys, caller-owned list/operation labels, disabled-item protection, preserved opposite-side selection, grouped list semantics, standard root DOM/ARIA/ref ownership and same-source Showcase coverage. The documented canonical path always provides `titles`/`operations`; pre-6D5 omitted labels remain a narrow compatibility bridge that injects no English list copy. Search, pagination, remote data and business collection rules remain product-owned.
+- Data Entry 6D4: hardened Core `Mentions` while preserving native multiline textarea/textbox semantics. `value/defaultValue/onChange` now form one string-state contract; literal prefixes drive local option filtering; suggestions are associated through standard autocomplete/listbox ARIA and support ArrowUp/ArrowDown/Enter/Escape selection. The component forwards the real textarea ref and reuses canonical Textarea sizing, validation status, count and native form/ARIA behavior. Remote search, debounce, user-resource loading and rich-token orchestration remain caller-owned.
+- Data Entry 6D3: hardened Core `InputOTP` around one digit-string value contract with caller-owned group naming, language-neutral numeric slot names, real root ref, canonical `small/middle/large` sizing, explicit `error/warning` status, digit sanitization, multi-digit paste distribution, automatic forward focus, empty-slot Backspace retreat and Arrow/Home/End positional navigation. Business verification, resend timers and completion policy remain product-owned.
+- Data Entry 6D2: hardened Core `Slider` and `Rate` without expanding them into feature bags. Slider remains a thin native `input[type=range]` control and now exposes the real input ref, stable slot and governed focus treatment while preserving platform range/form/keyboard semantics. Rate now uses caller-owned standard ARIA on its `radiogroup`, language-neutral numeric radio names, real root ref, stable slots, click-to-clear behavior and one roving-focus Arrow/Home/End keyboard selection model.
+- Data Entry 6D1: hardened Core `AutoComplete` around an accessible combobox/listbox contract with string shorthand or explicit `{ value, label, disabled }` options, caller-owned empty-state content, canonical `small/middle/large` sizing, explicit `error/warning` status, composed native input events, disabled-option keyboard skipping, real input ref and stable semantic slots. The existing `value/defaultValue/onChange` text state remains the single input value contract; `onSelect` reports confirmed suggestions without replacing `onChange`.
+- Data Entry 6C2: hardened Core `DateRangePicker` as a two-native-input compound control. The root now owns only range composition/layout while `startInputProps` and `endInputProps` independently own each date input's native attributes, form identity, ARIA naming, constraints and optional ref; canonical `size/status`, root ref, stable slots and same-source Showcase/tests are included without changing the established controlled `start/end/onChange` state model.
+- Data Entry 6C1: hardened Core `TimePicker` and `ColorPicker` while preserving native `input[type=time]` / `input[type=color]` semantics; both now share canonical `small/middle/large` control sizing, explicit `error/warning` status, standard DOM/ARIA extension, real input refs, stable `data-slot` anatomy, same-source Showcase examples and focused certification tests.
+- Layout 6B2: hardened Core `Splitter` around canonical `Splitter.Panel` compound composition with multiple panels, controlled/uncontrolled size vectors, per-panel constraints, pointer/keyboard resizing, resize lifecycle and separator ARIA; the established two-panel `first/second/defaultSize/min/max/onResize(number)` path remains deprecated-compatible rather than removed.
+- General/Layout 6B1: hardened Core `Avatar` and `Grid`; Avatar now follows canonical `small/middle/large | number` sizing while retaining deprecated `sm/default/lg` compatibility, exposes Group/Badge/Count compound anatomy, and Grid retains its simple helper while adding responsive 24-column `Row`/`Col`.
+- General/Layout 6A: hardened Core `Icon`, `Kbd`, `Flex` and `Separator` with ref-safe native contracts, standard ARIA, mature layout/line capabilities, semantic slots, same-source Showcase examples and focused certification tests.
+- Core reviewed-completion continues independently from runtime-family coverage; no established Core family is removed merely to raise completion percentages.
+
+### Breaking
+
+- `BackTop` now requires caller-owned `aria-label` and actually remains unrendered until `window.scrollY` reaches `visibilityHeight`; Core no longer injects the English `Back to top` label.
+- `Watermark.content` is now required; Core no longer defaults generic watermarks to `Gouno`.
+- `FloatButton` now requires `icon` and no longer injects a default `↑` glyph. Accessible names should be supplied with standard `aria-label` / `aria-labelledby`; `tooltip` renders visual Tooltip content and is not an implicit naming API.
+- `TourStep.target` is removed because Core never implemented target positioning/highlighting. `Tour` now requires caller-owned `previousText`, `nextText`, and `finishText` instead of injecting English copy; the visible step title names the modal dialog.
+- `Icon.label` is replaced by the standard `aria-label` / `aria-labelledby` accessible-name path.
+- `TimePicker.size` and `ColorPicker.size` now mean canonical Gouno control size (`small | middle | large`) rather than the native numeric input `size` attribute; the native numeric attribute is not meaningful for these picker controls and is intentionally excluded from the public contract.
+- `DateRangePicker` no longer copies one top-level set of input attributes to both date inputs or injects English `Start date` / `End date` accessible names. Per-input `id`, `name`, ARIA, constraints, events and refs belong under `startInputProps` / `endInputProps`; the root accepts normal div attributes. Existing `start`, `end` and `onChange` remain the range state contract.
+- `AutoComplete` no longer injects `No options` or reuses the native numeric input `size` attribute. Empty-state copy is opt-in through `emptyText`; `size` now follows Gouno `ControlSize`. The component-owned suggestion `onSelect(value, option)` intentionally replaces the native text-selection event of the same React prop name; consumers needing text-selection behavior should handle it through their surrounding input workflow rather than a second `onSelect` meaning.
+- `Rate.label` and injected English item names such as `"4 stars"` are removed. Name the rating group with standard `aria-label` / `aria-labelledby`; each radio now exposes its language-neutral numeric value within that named group. This avoids Core-owned locale copy while retaining one `value/defaultValue/onChange` rating state contract.
+- `InputOTP.ariaLabel` and injected English names such as `"One-time password"` / `"Digit 1"` are removed. Name the OTP group with standard `aria-label` / `aria-labelledby`; individual digit fields expose numeric position names within that context. `InputOTP` now owns one digit-string `value/defaultValue/onChange` contract and standard root DOM/ref semantics rather than a non-standard naming prop.
+- `Mentions.onChange` now reports the complete text string instead of exposing the native textarea `ChangeEvent`, making controlled and uncontrolled text ownership explicit. `Mentions.onSelect` remains the single suggestion-confirmation callback and intentionally excludes the native textarea text-selection event of the same prop name. The component retains native multiline textbox semantics rather than overriding the textarea with a single-line combobox role.
+
+## [0.2.0] - 2026-09-10
+
+`0.2.0` is the first product-validated release after the initial standalone package. It intentionally contains pre-1.0 breaking API corrections. See [`docs/migration.md`](docs/migration.md) for consumer migration details.
+
+### Added
+
+- Added the completed Gosso Admin, Blog Admin and Gouno Blog public Showcase corpora as live regression and abstraction evidence rather than simulated product demos.
+- Added canonical Core `CodeBlock` after independent Blog article and Showcase evidence converged on the same read-only code/copy contract; syntax highlighting remains caller-owned.
+- Added canonical Pattern `BulkActionBar` after multiple independent Blog Admin collection workflows proved one stable selection-toolbar interaction. It is the only currently admitted Pattern.
+- Added product-driven governance for abstraction admission, API conformance, design language, Core retention and runtime-family coverage.
+- Added a zero-pending Core runtime-family gate: every PascalCase Core runtime export must map to a visible Core Showcase family and cannot remain `needs-review` or `unassigned`.
+- Added focused behavior, accessibility, API-documentation, architecture, product-fixture and source-trust regression coverage across the validated component surface.
+
+### Changed
+
+- Formalized the public dependency/ownership chain as `Core -> Theme -> Patterns -> Gouno`; the package root remains a compatibility umbrella rather than a fifth owner.
+- Curated package entry points and explicit symbol manifests; canonical implementation and Showcase consume formal layer entry points rather than source-directory wildcards or the root umbrella.
+- Quarantined `src/legacy` outside canonical builds, publication, Showcase and dependency flow. Legacy is prior art only, not a compatibility layer or naming precedent.
+- Re-admitted only evidence-backed Gouno structure: `AppShell`, `PageContainer`, `PageHeader`, `NavigationGroup` and `navigationItemClass`.
+- Hardened Tabs around one high-level state contract: `activeKey`, `defaultActiveKey`, `items[].key`, `onChange`. Primitive `Tab` / `TabPanel value` remains only the composition key. Standard `aria-label` / `aria-labelledby` is canonical; `ariaLabel` remains temporarily as an explicit deprecated bridge for atomic real-product artifact upgrades.
+- Hardened `Steps` and `Menu` around stable keys, explicit selection/expansion state, hierarchical navigation and keyboard/accessibility behavior without compatibility feature bags or injected English accessible copy.
+- Hardened `Empty`, `Result`, `Skeleton`, `QRCode`, `Statistic`, `Spin` and `Spinner` so product copy, live-region policy, surface/elevation and standard DOM/ARIA ownership stay explicit rather than being injected as hidden defaults.
+- Hardened `Segmented`, `Anchor`, `Alert`, `Modal`, `Card`, Table row-action composition and other Core families from real product pressure tests while keeping domain orchestration product-owned.
+- Standardized compound spacing and surface ownership: parents own structural spacing between semantic slots; content regions own internal padding/rhythm; Tabs indicators stay inside the TabList scroll boundary.
+- Standardized semantic elevation roles and product-surface rules, replacing ad-hoc page-level shadow-size decisions with governed `control`, `surface`, `raised`, `overlay` and `modal` responsibilities.
+- Assigned retained convenience/compound APIs to canonical families without deleting them merely for low usage: `SearchField -> Input`, `CheckboxField -> Checkbox`, `AvatarImage`/`AvatarFallback -> Avatar`, `Divider -> Separator`, `App`/`Container`/`AspectRatio`/`Stack` remain retained and assigned to their canonical Layout/Flex families.
+- Upgraded the verification/publish baseline to Node.js 24 with immutable SHA-pinned GitHub Actions; main must pass typecheck, the complete test suite, package build and Showcase build before Pages publication.
+
+### Removed / Breaking
+
+- Removed speculative public Pattern/Gouno surfaces that were not re-proven by real products, including the historical broad DataTable/Toast/Feedback/AsyncState/page-utility feature bags. Their Legacy snapshots remain non-public prior art only.
+- Removed inert global configuration APIs such as `ConfigProvider`, `useConfig` and `UIConfig` when no canonical component consumed their configuration.
+- Removed public source-directory wildcard subpaths and duplicate ownership/re-export paths.
+- Removed duplicate Pattern-level Tabs/Pagination implementations and `SubnavTabs`; Core is the single owner.
+- Removed high-level Tabs `value`, `defaultValue`, `items[].value` and `onValueChange` compatibility paths. Consumers must use the canonical keyed contract.
+- Removed or renamed non-canonical compatibility inputs as documented in the migration guide, including affected Alert, Empty, Result, QRCode, Steps and Menu contracts. No aliases are added merely to preserve historical Gouno/Legacy naming.
+
+### Delivery
+
+- The three completed product corpora remain in Showcase as comparison/regression evidence; there is intentionally no fabricated fourth-product migration line.
+- Main validation now treats a phase as complete only after exact-head CI passes and the matching Showcase commit is published to `gh-pages`.
+
+## [0.1.0] - 2026-09-05
+
+### Added
+
+- Initial standalone `@gouno/ui` package with semantic themes, local fonts, accessible Radix-based primitives, Core components, reusable Patterns, Gouno product templates, and a static Showcase.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gouno UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @gouno/ui
+
+Shared React UI system for the Gouno product family: product-agnostic Core, dedicated Theme, product-driven Pattern/Gouno abstractions, and a static Showcase used as component documentation plus real-page validation.
+
+**Live Showcase:** https://rushairer.github.io/gouno-ui/
+
+## Install
+
+```bash
+npm install @gouno/ui
+```
+
+`@gouno/ui` is published as an immutable public npm package. Gouno products should initially pin an exact version and upgrade it through a normal dependency PR rather than tracking mutable archives or repository branches.
+
+For Tailwind CSS v4 consumers, import Tailwind once, then the canonical tokens/base styles, and register the package dist directory as a Tailwind source:
+
+```css
+@import "tailwindcss";
+@import "@gouno/ui/tokens.css";
+@import "@gouno/ui/base.css";
+
+@source "../node_modules/@gouno/ui/dist";
+```
+
+Use the formal public entry points rather than source paths:
+
+```tsx
+import { Button, Card } from "@gouno/ui/core";
+import { ThemeProvider } from "@gouno/ui/theme";
+import { BulkActionBar } from "@gouno/ui/patterns";
+import { AppShell, PageContainer, PageHeader } from "@gouno/ui/gouno";
+```
+
+React and React DOM are peer dependencies. See [`docs/releasing.md`](docs/releasing.md) for the immutable npm release contract.
+
+## Architecture
+
+Formal public owners:
+
+- `src/core` — product-agnostic controls, layout, data entry/display, navigation, feedback and overlays.
+- `src/theme` — brand/theme state, persistence and controls.
+- `src/patterns` — admitted reusable compound interactions. Current runtime surface: `BulkActionBar`.
+- `src/gouno` — admitted Gouno product-family structure/policy. Current runtime surface: `AppShell`, `PageContainer`, `PageHeader`, `NavigationGroup`, `navigationItemClass`.
+
+```text
+components/primitives + lib → Core → Theme → Patterns → Gouno
+```
+
+`src/legacy` has been removed from the current source tree. Historical implementations live in Git history; do not recreate a Legacy, Candidates or Incubator source layer.
+
+See [`docs/architecture.md`](docs/architecture.md) and [`docs/product-driven-development.md`](docs/product-driven-development.md).
+
+## Public entry points
+
+```ts
+import { Button, CodeBlock, Pagination, Table, Tabs } from "@gouno/ui/core";
+import { ThemeProvider, ThemeToggle, useTheme } from "@gouno/ui/theme";
+import { BulkActionBar } from "@gouno/ui/patterns";
+import { AppShell, PageContainer, PageHeader } from "@gouno/ui/gouno";
+```
+
+`BulkActionBar` is the first admitted Pattern. It was extracted only after three independently rebuilt Blog Admin workflows (Posts, Comments and Categories) converged on the same selection-aware toolbar interaction. Its API intentionally excludes resource-specific or AI-specific shortcuts.
+
+`CodeBlock` was admitted to Core only after the real Blog article renderer independently proved the same read-only code frame, horizontal overflow and copy-feedback contract that Showcase had previously exercised privately. Core deliberately does not own a syntax highlighter; consumers may inject token rendering through `renderCode(code)` while `code` remains the sole display/copy source.
+
+The root `@gouno/ui` is an external compatibility umbrella, not a fifth owner. Repository implementation and Showcase import canonical formal layers instead. Source wildcard paths and historical Legacy package paths are not public API.
+
+## Product-driven evolution
+
+Three real product corpora are now closed as comparison evidence:
+
+- **Gosso Admin** — completed first-product corpus after route coverage plus product-language convergence.
+- **Blog Admin** — completed second-product corpus after route coverage plus behavior/detail fidelity hardening.
+- **Gouno Blog public site** — completed third-product corpus after PublicShell/Home, discovery, reading, document, account and final NotFound route-family validation.
+- **No active fourth-product migration line is selected.** New product migration starts only when a real independently owned product/page family is chosen, or when a completed corpus exposes a genuine canonical defect that requires reopening a component or fixture.
+
+Pages still start Core-first with Theme, admitted Gouno structure where semantics match, and local composition. Public-site document/content shells are not forced into `AppShell` merely for visual consistency. Small repetition is preferred over premature extraction, and the third semantically equivalent occurrence still triggers review rather than automatic extraction.
+
+Before a Pattern/Gouno addition or material Core extension, compare canonical UI, relevant Git history when historical prior art is useful, and matching real product cases across all completed corpora. Durable decisions live in [`docs/abstraction-register.md`](docs/abstraction-register.md); public naming/state/composition rules live in [`docs/api-specification.md`](docs/api-specification.md).
+
+Current admitted abstractions demonstrate the process rather than a fixed catalog: `AppShell`/`PageContainer` were the initial shell baseline; `PageHeader` was re-admitted only after real page evidence; `BulkActionBar` became the first Pattern only after three different migrated collection workflows proved a smaller shared interaction than the surrounding page structures; `CodeBlock` moved from Showcase-private tooling into Core only when the public Blog reading path supplied independent product demand.
+
+## Showcase role
+
+Showcase separates product workspace from design-system ownership:
+
+- **Gouno UI** — canonical `Core / Theme / Patterns / Gouno` documentation.
+- **Gosso Admin** — completed first-product comparison corpus.
+- **Blog Admin** — completed second-product comparison corpus.
+- **Blog** — completed third-product public-site comparison corpus.
+
+There is currently no active product workspace receiving page-by-page migration. Completed workspaces stay live as regression/comparison evidence and may be reopened only when a real new product or a discovered canonical defect creates demand.
+
+Showcase dogfoods admitted canonical APIs. `CodeBlock` is now a canonical Core component, while Showcase's Prism renderer remains a private adapter layered on top of it. API tables, demo framing, viewport simulation and similar documentation tooling remain private; Showcase-only repetition is supporting evidence and cannot create another public abstraction by itself.
+
+Every PascalCase Core runtime export is now assigned to a visible Core Showcase family. The coverage gate rejects `needs-review` and `unassigned` entries; established Core APIs follow the explicit retention policy rather than being removed solely because no current product calls them.
+
+## Tabs
+
+Core Tabs uses a mature high-level contract while retaining Radix-backed accessibility/composition:
+
+```tsx
+<Tabs
+  aria-label="Account sections"
+  activeKey={activeKey}
+  items={[
+    { key: "profile", label: "Profile" },
+    { key: "security", label: "Security" },
+  ]}
+  onChange={setActiveKey}
+/>
+```
+
+Canonical state names are `activeKey`, `defaultActiveKey`, `items[].key`, `onChange`. The pre-reset high-level `value`, `defaultValue` and `items[].value` compatibility inputs have been removed. Primitive `Tab`/`TabPanel` still use `value` only as their composition key. Standard `aria-label` / `aria-labelledby` is canonical; `ariaLabel` remains temporarily as an explicitly deprecated real-product migration bridge until vendored artifacts are refreshed. The default `type="line"` uses a lightweight ink-bar style; `type="card"` is explicit. See [`docs/migration.md`](docs/migration.md) for the breaking migration details.
+
+## Neutral application structure
+
+```tsx
+<AppShell brand="GOSSO" navigation={renderNavigation}>
+  <PageContainer>
+    <PageHeader
+      title="OAuth2 客户端"
+      description="管理客户端注册与授权配置。"
+      actions={<Button>注册客户端</Button>}
+    />
+    <RouteContent />
+  </PageContainer>
+</AppShell>
+```
+
+`AppShell` owns application chrome, `PageContainer` owns content width/rhythm, and `PageHeader` owns only page title/description/actions presentation. Routing, authentication, permissions, filtering, tables and business state stay in the consuming product unless separately admitted.
+
+## Build and verification
+
+```bash
+npm ci
+npm run release:check
+```
+
+`release:check` runs typecheck, the full test suite, package build, Showcase build and the publication-surface check. `npm run package:check` additionally verifies that formal entry points load from `dist` and that `npm pack --dry-run` contains the required public files without leaking source, Showcase, docs, scripts or workflow internals.
+
+Main CI uses the same Node.js 24 release gate before publishing Showcase to `gh-pages`. Pull requests run the same release-readiness check. Stable npm publication is tag-driven; see [`docs/releasing.md`](docs/releasing.md).
+
+Run `npm run showcase:dev` for local documentation/product scenarios. Showcase fixtures are static: they do not authenticate, read cookies, call APIs or mutate real application state.

package/dist/base.css

@@ -0,0 +1,239 @@
+@font-face {
+  font-family: "Inter Variable";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("./fonts/inter-latin-wght-normal.woff2") format("woff2");
+}
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("./fonts/jetbrains-mono-latin-400-normal.woff2") format("woff2");
+}
+@layer base {
+  * {
+    border-color: var(--border);
+  }
+  html {
+    color-scheme: light dark;
+    scroll-padding-top: 80px;
+  }
+  body {
+    margin: 0;
+    background: var(--background);
+    color: var(--foreground);
+    font-family: var(--font-sans);
+    font-size: 14px;
+    line-height: 1.6;
+    -webkit-font-smoothing: antialiased;
+  }
+  body,
+  #root {
+    min-height: 100vh;
+  }
+  button,
+  input,
+  select,
+  textarea {
+    font: inherit;
+  }
+  button:not(:disabled),
+  [role="button"]:not([aria-disabled="true"]) {
+    cursor: pointer;
+  }
+  :focus-visible {
+    outline: 2px solid var(--ring);
+    outline-offset: 3px;
+  }
+  ::selection {
+    background: var(--accent);
+    color: var(--accent-foreground);
+  }
+  img {
+    max-width: 100%;
+  }
+  pre,
+  code,
+  kbd {
+    font-family: var(--font-mono);
+  }
+  th {
+    text-align: start;
+  }
+  [data-slot="table-head"] {
+    color: var(--muted-foreground);
+  }
+  [data-slot="table-cell"],
+  [data-slot="table-head"] {
+    box-sizing: border-box;
+    padding: 12px 16px;
+  }
+  [data-slot="table-head"] {
+    height: 40px;
+  }
+  [data-slot="table-row"]:hover {
+    background: var(--muted);
+  }
+  [data-slot="dialog-overlay"],
+  [data-slot="sheet-overlay"],
+  [data-slot="alert-dialog-overlay"] {
+    background: var(--overlay);
+  }
+  [data-slot="dialog-content"] {
+    max-height: 92dvh;
+    overflow-y: auto;
+  }
+  [data-slot="sheet-content"] {
+    max-height: 100dvh;
+    overflow-y: auto;
+  }
+  [data-slot="dialog-content"] {
+    width: calc(100% - 32px);
+  }
+  [data-slot="button"] {
+    border-radius: var(--radius-control);
+  }
+  [data-slot="button"] svg {
+    width: 16px;
+    height: 16px;
+    flex-shrink: 0;
+  }
+  @media (max-width: 767px) {
+    [data-slot="button"],
+    [data-slot="input"],
+    [data-slot="select-trigger"] {
+      min-height: 44px;
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0s;
+      transition-duration: 0s;
+      scroll-behavior: auto;
+    }
+  }
+}
+
+@keyframes gouno-carousel-dot {
+  from {
+    transform: scaleX(0);
+  }
+  to {
+    transform: scaleX(1);
+  }
+}
+
+@layer components {
+  .form-layout--horizontal .field {
+    display: grid;
+    grid-template-columns: minmax(8rem, 12rem) minmax(0, 1fr);
+    align-items: start;
+    column-gap: 16px;
+  }
+  .form-layout--horizontal .field > [data-slot="field-label"] {
+    padding-top: 8px;
+    text-align: end;
+  }
+  .form-layout--horizontal .field > [data-slot="field-description"],
+  .form-layout--horizontal .field > [data-slot="field-error"] {
+    grid-column: 2;
+  }
+  @media (max-width: 767px) {
+    .form-layout--horizontal .field {
+      display: flex;
+      flex-direction: column;
+      gap: 6px;
+    }
+    .form-layout--horizontal .field > [data-slot="field-label"] {
+      padding-top: 0;
+      text-align: start;
+    }
+  }
+  [data-slot="table-container"][data-density="compact"]
+    [data-slot="table-head"] {
+    height: 36px;
+    padding: 8px 12px;
+  }
+  [data-slot="table-container"][data-density="compact"]
+    [data-slot="table-cell"] {
+    padding: 8px 12px;
+  }
+  [data-slot="table-container"][data-density="touch"] [data-slot="table-head"] {
+    height: 48px;
+    padding: 14px 16px;
+  }
+  [data-slot="table-container"][data-density="touch"] [data-slot="table-cell"] {
+    padding: 14px 16px;
+  }
+
+  /* Icon-only actions share one size, optical center, and state treatment. */
+  .icon-button {
+    display: inline-flex;
+    width: 36px;
+    height: 36px;
+    min-height: 36px;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    line-height: 1;
+  }
+
+  .icon-button > .btn__icon {
+    display: inline-flex;
+    width: 16px;
+    height: 16px;
+    align-items: center;
+    justify-content: center;
+    line-height: 1;
+  }
+
+  .icon-button > .btn__icon > svg {
+    display: block;
+    width: 16px;
+    height: 16px;
+    flex: 0 0 16px;
+  }
+}
+
+@layer components {
+  /* Core 24-column Row/Col responsive contract. */
+  [data-slot="col"] {
+    box-sizing: border-box;
+    position: relative;
+    flex: 0 0 var(--gouno-col-basis);
+    max-width: var(--gouno-col-basis);
+    margin-inline-start: var(--gouno-col-offset);
+    inset-inline-start: var(--gouno-col-shift);
+    order: var(--gouno-col-order);
+  }
+  [data-slot="col"][data-span="0"] { display: none; }
+  @media (min-width: 640px) {
+    [data-slot="col"] { flex-basis: var(--gouno-col-sm-basis); max-width: var(--gouno-col-sm-basis); margin-inline-start: var(--gouno-col-sm-offset); inset-inline-start: var(--gouno-col-sm-shift); order: var(--gouno-col-sm-order); }
+    [data-slot="col"][data-sm-span="0"] { display: none; }
+    [data-slot="col"]:not([data-sm-span="0"]) { display: block; }
+  }
+  @media (min-width: 768px) {
+    [data-slot="col"] { flex-basis: var(--gouno-col-md-basis); max-width: var(--gouno-col-md-basis); margin-inline-start: var(--gouno-col-md-offset); inset-inline-start: var(--gouno-col-md-shift); order: var(--gouno-col-md-order); }
+    [data-slot="col"][data-md-span="0"] { display: none; }
+    [data-slot="col"]:not([data-md-span="0"]) { display: block; }
+  }
+  @media (min-width: 1024px) {
+    [data-slot="col"] { flex-basis: var(--gouno-col-lg-basis); max-width: var(--gouno-col-lg-basis); margin-inline-start: var(--gouno-col-lg-offset); inset-inline-start: var(--gouno-col-lg-shift); order: var(--gouno-col-lg-order); }
+    [data-slot="col"][data-lg-span="0"] { display: none; }
+    [data-slot="col"]:not([data-lg-span="0"]) { display: block; }
+  }
+  @media (min-width: 1280px) {
+    [data-slot="col"] { flex-basis: var(--gouno-col-xl-basis); max-width: var(--gouno-col-xl-basis); margin-inline-start: var(--gouno-col-xl-offset); inset-inline-start: var(--gouno-col-xl-shift); order: var(--gouno-col-xl-order); }
+    [data-slot="col"][data-xl-span="0"] { display: none; }
+    [data-slot="col"]:not([data-xl-span="0"]) { display: block; }
+  }
+  @media (min-width: 1536px) {
+    [data-slot="col"] { flex-basis: var(--gouno-col-xxl-basis); max-width: var(--gouno-col-xxl-basis); margin-inline-start: var(--gouno-col-xxl-offset); inset-inline-start: var(--gouno-col-xxl-shift); order: var(--gouno-col-xxl-order); }
+    [data-slot="col"][data-xxl-span="0"] { display: none; }
+    [data-slot="col"]:not([data-xxl-span="0"]) { display: block; }
+  }
+}

package/dist/bootstrap.js

@@ -0,0 +1,22 @@
+/* Same-origin, parser-blocking bootstrap. No auth state is read or written. */
+(() => {
+  const script = document.currentScript;
+  const key = script?.dataset.storageKey || "gouno-blog:theme";
+  let mode = "system";
+  try {
+    const stored = localStorage.getItem(key);
+    if (stored === "light" || stored === "dark") mode = stored;
+  } catch {}
+  const resolved =
+    mode === "system"
+      ? window.matchMedia("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light"
+      : mode;
+  const root = document.documentElement;
+  root.dataset.theme = resolved;
+  root.dataset.brand =
+    script?.dataset.brand ||
+    (/^\/admin(?:\/|$)/.test(location.pathname) ? "blog-admin" : "blog");
+  root.style.colorScheme = resolved;
+})();

package/dist/components/primitives/alert-dialog.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+import { AlertDialog as AlertDialogPrimitive } from "radix-ui";
+import { Button } from "./button.js";
+declare function AlertDialog({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Root>): React.JSX.Element;
+declare function AlertDialogTrigger({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>): React.JSX.Element;
+declare function AlertDialogPortal({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Portal>): React.JSX.Element;
+declare function AlertDialogOverlay({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>): React.JSX.Element;
+declare function AlertDialogContent({ className, size, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Content> & {
+    size?: "default" | "sm";
+}): React.JSX.Element;
+declare function AlertDialogHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertDialogFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertDialogTitle({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Title>): React.JSX.Element;
+declare function AlertDialogDescription({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Description>): React.JSX.Element;
+declare function AlertDialogMedia({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertDialogAction({ className, variant, size, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Action> & Pick<React.ComponentProps<typeof Button>, "variant" | "size">): React.JSX.Element;
+declare function AlertDialogCancel({ className, variant, size, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Cancel> & Pick<React.ComponentProps<typeof Button>, "variant" | "size">): React.JSX.Element;
+export { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, };

package/dist/components/primitives/alert-dialog.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+import { AlertDialog as AlertDialogPrimitive } from "radix-ui";
+import { Button } from "./button.js";
+function AlertDialog({ ...props }) {
+    return _jsx(AlertDialogPrimitive.Root, { "data-slot": "alert-dialog", ...props });
+}
+function AlertDialogTrigger({ ...props }) {
+    return (_jsx(AlertDialogPrimitive.Trigger, { "data-slot": "alert-dialog-trigger", ...props }));
+}
+function AlertDialogPortal({ ...props }) {
+    return (_jsx(AlertDialogPrimitive.Portal, { "data-slot": "alert-dialog-portal", ...props }));
+}
+function AlertDialogOverlay({ className, ...props }) {
+    return (_jsx(AlertDialogPrimitive.Overlay, { "data-slot": "alert-dialog-overlay", className: cn("fixed inset-0 z-50 bg-overlay data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0", className), ...props }));
+}
+function AlertDialogContent({ className, size = "default", ...props }) {
+    return (_jsxs(AlertDialogPortal, { children: [_jsx(AlertDialogOverlay, {}), _jsx(AlertDialogPrimitive.Content, { "data-slot": "alert-dialog-content", "data-size": size, className: cn("group/alert-dialog-content fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border bg-popover p-6 shadow-modal duration-150 data-[size=sm]:max-w-xs data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[size=default]:sm:max-w-lg", className), ...props })] }));
+}
+function AlertDialogHeader({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-dialog-header", className: cn("grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center has-data-[slot=alert-dialog-media]:grid-rows-[auto_auto_1fr] has-data-[slot=alert-dialog-media]:gap-x-6 sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left sm:group-data-[size=default]/alert-dialog-content:has-data-[slot=alert-dialog-media]:grid-rows-[auto_1fr]", className), ...props }));
+}
+function AlertDialogFooter({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-dialog-footer", className: cn("flex flex-col-reverse gap-2 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end", className), ...props }));
+}
+function AlertDialogTitle({ className, ...props }) {
+    return (_jsx(AlertDialogPrimitive.Title, { "data-slot": "alert-dialog-title", className: cn("text-lg font-semibold sm:group-data-[size=default]/alert-dialog-content:group-has-data-[slot=alert-dialog-media]/alert-dialog-content:col-start-2", className), ...props }));
+}
+function AlertDialogDescription({ className, ...props }) {
+    return (_jsx(AlertDialogPrimitive.Description, { "data-slot": "alert-dialog-description", className: cn("text-sm text-muted-foreground", className), ...props }));
+}
+function AlertDialogMedia({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-dialog-media", className: cn("mb-2 inline-flex size-16 items-center justify-center rounded-md bg-muted sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-8", className), ...props }));
+}
+function AlertDialogAction({ className, variant = "default", size = "default", ...props }) {
+    return (_jsx(Button, { variant: variant, size: size, asChild: true, children: _jsx(AlertDialogPrimitive.Action, { "data-slot": "alert-dialog-action", className: cn(className), ...props }) }));
+}
+function AlertDialogCancel({ className, variant = "outline", size = "default", ...props }) {
+    return (_jsx(Button, { variant: variant, size: size, asChild: true, children: _jsx(AlertDialogPrimitive.Cancel, { "data-slot": "alert-dialog-cancel", className: cn(className), ...props }) }));
+}
+export { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, };

package/dist/components/primitives/alert.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const alertVariants: (props?: ({
+    variant?: "default" | "destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Alert({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>): React.JSX.Element;
+declare function AlertTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { Alert, AlertTitle, AlertDescription };