@krigsvold/theme 2.0.0 → 2.2.0

package/docs/layout.md

@@ -0,0 +1,20 @@
+# Krigsvold layout extraction
+
+Release candidate: core 2.1.0 and Astro 1.1.0. Existing color, font, and component contracts remain available.
+
+## Source observations
+
+- Originating site: [krigsvold.org](https://github.com/basuhoward/krigsvold.org/tree/a3cf072c516c59ed35814e0fa153028cc91ceecd). Inspected files: `src/layouts/Page.astro`, `src/components/HomeContent.astro`, `src/components/HomeHero.astro`, `src/styles/site.css`.
+- Demonstration site: [krigsvoldtheme.dev](https://github.com/krigsvoldtheme/krigsvoldtheme/tree/880bdd2bd8430bbdfd8d728faaae0c21199540b1). Inspected files: `site/src/pages/index.astro`, `site/src/styles/global.css`, `site/src/components/FoundationSpecimen.astro`.
+
+The originating site uses broad section bands, paired geography and feature regions, three-column work/metric groups, a main article plus fellowship facts, and image/copy listings. The demonstration site adds a full-width landscape opening, a single workbench, a paired contrast/token laboratory, and a three-card foundation specimen.
+
+## Reusable contract
+
+The core retains its original reading/content/archive widths. New layout variables normalize recurring gaps, a 20rem sidebar, a 30rem minimum main region, a 20rem card minimum, and a 22rem split-panel basis. These are documented defaults, not a claim that every source element used exactly the same values. Krigsvold's default split is `equal`.
+
+Use `@krigsvold/theme/layout.css` with foundation variables for structural classes; it loads no fonts or palette. `full.css` includes it. `layout.json` and the ESM/CommonJS `layout` export describe defaults and provenance. No existing source value is silently replaced.
+
+Intrinsic wrapping responds to the containing region. Grid `columns` is a maximum, not a promise to fit that many columns at every width. Sidebars use a separate main-content minimum; splits retain DOM order. There is no overflow-hiding workaround. Wide tables belong in a labelled `.krigsvold-scroll` region with `tabindex="0"` when keyboard scrolling is needed.
+
+The Astro package supplies wrappers, site chrome, and complete article, landing, and documentation compositions. Identity, route generation, content rendering, analytics, and consent remain host-owned. Header links wrap naturally; this release does not implement dropdown or disclosure-menu behavior.

package/docs/patterns/forms.md

@@ -0,0 +1,37 @@
+# Krigsvold: a validated form
+
+Experimental pattern contract 0.3 · Application extension · React reference specimen
+
+## Purpose and composition
+
+Use this pattern for a deliberate submission with multiple related fields and recoverable errors. The specimen is a publication request with title, summary, request type, response name/address and a notification preference. It is a controlled documentation example; it sends nothing and stores nothing beyond the mounted specimen.
+
+Define a request region, a response region and a command region. Use shared edges within each region, and a restrained boundary only where the job changes. Short related fields may align in columns when space permits. Supporting guidance follows the work in source order and can sit beside it when each region retains useful width. The command row belongs to the form it commits.
+
+Use the field relationship for label, control, hint and error; group spacing for sibling fields; and region spacing between different decisions. A native fieldset and legend identify a real group. Do not add a card per field. Keep the primary submit action after the editable groups. Secondary discard/reset actions describe their consequence and remain visually subordinate. The specimen uses comfortable density; it introduces no compact-density API.
+
+## Validation and state transitions
+
+| Trigger | Result | Focus and retained work |
+| --- | --- | --- |
+| Submit invalid fields | Show a summary and field-linked errors; mark only invalid controls. | Focus the summary; its links focus the actual controls. Keep all input. |
+| Edit after an error | Retain the error until revalidation on submission. | Keep focus in the edited field. Do not announce validation on every keystroke. |
+| Submit valid data | Enter pending state and prevent another submission. | Keep the form visible; make inputs temporarily unavailable and announce saving. |
+| Simulated save failure | Explain that work is retained and offer retry. | Focus the actionable failure summary; preserve every field and preference. |
+| Retry successfully | Commit the submitted values to the local example state and announce success. | Keep the same form and orientation; do not clear fields or move focus merely for success. |
+| Reset a changed specimen | Open a native confirmation dialog with Keep editing and Discard changes. | Escape and Keep editing preserve the draft and return focus to Reset specimen. Discard resets the specimen and returns focus to that trigger. |
+| Reset an unchanged specimen | Reset immediately. | Preserve orientation; no unnecessary dialog. |
+
+The pending operation is short and simulated. Unmounting invalidates its completion; a late timer cannot update another specimen. Reset is unavailable while saving. The draft guard covers the specimen's Reset action; documentation navigation is outside that guard and unmounts the example. This is an explicit hosting boundary, not a claim of full application navigation protection.
+
+## Semantics and responsive behavior
+
+Use native form, label, input, select, textarea, checkbox, fieldset and button semantics. Required indicators appear in labels and requirements in hints. Read-only text remains inspectable and available to native form behavior; disabled controls are temporarily unavailable. Do not invent readOnly support for a native select or checkbox. Name the form, error summary and dialog, and expose meaningful pending/saved state without repeated announcements.
+
+At narrow widths the groups and actions stack in source order. Long text and enlarged text wrap without clipping. The guidance region follows the fields; no visual reordering changes keyboard order. Reduced motion does not remove state text. For print, retain the current values and context; hide only documentation inspection controls.
+
+## Implementation and evidence boundaries
+
+React composes Field, TextInput, Textarea, Select, Checkbox, Fieldset, Button, ErrorSummary and Dialog. These are existing exports; no new form-controller API is implied. Core supplies typography and spacing roles. Astro can express the same native HTML structure, but validation, transport, draft management and focus transitions remain host code; there is no Astro Form controller in this candidate.
+
+The reference includes validation, pending, failed/retry, saved and discard-dialog examples. Browser assertions cover values, linked errors, focus restoration, reflow and automated accessibility. Real server errors, conflict resolution, authentication, uploads and manual assistive-technology review remain outside this specimen. New controls and full dark mode remain experimental.

package/docs/patterns/query-results.md

@@ -0,0 +1,42 @@
+# Krigsvold: query, results and selection
+
+Experimental pattern contract 0.3 · Application extension · React reference specimen
+
+## Purpose and composition
+
+Use a results table when the task benefits from comparing several attributes across records. The reference uses the existing component catalogue as its dataset. Search, group filter, sorting, paging and selection are host logic composed from existing primitives. The preparation dialog makes no remote request or actual review decision.
+
+Give query, committed results and selection commands separate jobs. Align names, groups and purposes within the table so comparisons share common edges. Keep the applied scope and pending request distinguishable. Selected-item commands operate on the visible result page and stay beside its count. These regional rules apply whether the query sits above or beside the work.
+
+Visible search and filter labels name their scope. Enter or Apply query submits the draft query. Changing an unapplied input does not relabel old results. Show the committed query, result count and page independently of what is being typed. Put a table caption on the table and a keyboard-accessible name on its scrolling region. Do not make every row simultaneously mean selection, navigation and editing.
+
+## Query and result contract
+
+| Event | Required behavior |
+| --- | --- |
+| Apply a changed search, filter or sort | Start at page 1. Retain old results with their applied-scope label while pending. Disable selection commands during the transition. |
+| Pending result request | Announce loading, mark the result region busy, and retain useful content. Do not label previous results as matches for the new request. |
+| Request fails | Explain that the previous results are still shown; preserve the failed request for Retry. Keep its old selection, with commands unavailable until results are current. |
+| Retry succeeds | Commit the new result scope and announce its count. Clear the old page selection. |
+| Change page | Request the page within the committed query/filter/sort; clear selection when the new page commits. |
+| Refresh unchanged results | Retain selected identities that are still on the committed page. Do not restore selection by row index. |
+| No matches | Name the applied scope and offer Clear query; retain the dataset. |
+| Empty source dataset | Explain that no source records exist; do not present it as a failed query. |
+
+The reference simulates asynchronous completion and an optional one-shot failure. Each request carries a generation: an obsolete completion cannot replace newer state or update an unmounted specimen. The available sample data and sorting are deterministic. No remote retrieval, server pagination or durable selection is claimed.
+
+## Selection and dialog contract
+
+Selection means the checked records on the currently committed result page. Native checkboxes name each record. There is no select-all control, cross-page selection, mixed checkbox state or implied edit permission in this contract. The count is textual; row color is supplementary. Query/filter/sort/page changes clear selection only when their new result set commits. A failed request retains previous selection and scope for recovery.
+
+Review selection opens a native modal listing the exact selected component names. Prepare comparison is a simulated operation. Failure keeps the dialog and selection available for retry. Success closes the dialog, retains selection and announces completion. Cancel or Escape cancels an in-flight preparation, preserves selection and returns focus to Review selection. A late completion cannot announce success after dismissal. No action in this specimen promotes component maturity or records a real readiness review.
+
+Native dialog semantics make the background inert and keep modal keyboard behavior conventional. Non-modal navigation popups and disclosures do not inherit that modal contract or require a backdrop.
+
+## Responsive behavior and implementation
+
+Query controls wrap into one coherent sequence; status and commands wrap without clipping. A genuinely comparative table may scroll within its labelled region at narrow widths. Keep its caption, row-selection labels and all columns. Do not hide data or turn each row into a different task simply to remove horizontal scrolling. Surrounding prose and controls must still reflow.
+
+React uses Field, TextInput, Select, Checkbox, DataTable, Pagination, Button and Dialog. A host owns querying, sorting, paging, selection and request cancellation. Core owns the existing family styles. Astro native HTML guidance shares these semantics, but an interactive results controller is not supplied by the Astro package. Both languages permit a table or a list when the task supports it; neither is compulsory for one family.
+
+Tests exercise changed/unapplied scope, pending and failed retrieval, retry, no matches, paging, selection reset, modal failure/cancel/success, focus restoration, long text, narrow reflow and automated accessibility. Manual screen-reader review, localization/RTL, large datasets and real network races remain open consumer work.

package/docs/releasing.md

@@ -0,0 +1,27 @@
+# Automated npm releases
+
+GitHub Actions publishes stable GitHub releases through npm trusted publishing (OIDC), using `.github/workflows/publish.yml`. It requires no npm token secret.
+
+## One-time npm setup
+
+Open [package settings](https://www.npmjs.com/package/@krigsvold/theme/access), then Trusted publishing, Add trusted publisher, GitHub Actions. Enter these exact values:
+
+| Setting | Value |
+| --- | --- |
+| Organization/user | `krigsvoldtheme` |
+| Repository | `npm` |
+| Workflow filename | `publish.yml` |
+| Environment | Leave blank |
+| Allowed action | Enable direct `npm publish` |
+
+The workflow must be merged before use. New trusted publisher connections must complete their first publish within two days; otherwise recreate the connection. Existing package maintainers configure this on npm. No npm account settings are changed by this PR.
+
+## Release
+
+1. Merge reviewed version and changelog changes to `main`.
+2. Publish a stable GitHub release whose tag is exactly `v` plus `package.json`'s version.
+3. The workflow runs the full verification suite, checks tag/version/repository identity and ancestry in `main`, builds from a fresh install, and publishes to npm. Failed checks prevent publication.
+
+Release core 2.1.0 before Astro 1.1.0, then migrate the demonstration sites to registry versions. Prereleases do not publish through this stable-release workflow. Re-running a successful release fails rather than overwriting an existing npm version. Public repositories produce provenance attestations; private repositories publish with provenance disabled because npm does not support those attestations from private source repositories. Repository visibility is unchanged.
+
+Reference: https://docs.npmjs.com/trusted-publishers/

package/docs/source-decisions.md

@@ -0,0 +1,51 @@
+# Krigsvold source decisions
+
+Origin reconciliation 0.2 · Consolidation candidate · Original palette and existing defaults retained
+
+Use krigsvold.org as the authority for existing objects. This profile distinguishes restored source roles from application extensions. The full grammar remains experimental. Original source commit: `a3cf072c516c59ed35814e0fa153028cc91ceecd`, repository `basuhoward/krigsvold.org`. Review `src/styles/site.css`, `src/components/SiteHeader.astro`, `SiteFooter.astro`, `src/layouts/Page.astro` and active Material Kit styles. The audit and reconciliation ledger record evidence and remaining limits.
+
+## Existing source objects
+
+| Role | Decision | Source / reason |
+| --- | --- | --- |
+| Canvas/type | Paper #fbfaf7, ink #17202a, Roboto 1rem/1.65. Editorial prose 1.06rem/1.65. | Host overrides and live origin. |
+| Headings | Roboto Slab, weight 700, source scale/leading/tracking. | Source global/editorial/masthead roles. Medium-weight alternate docs headings were removed. |
+| UI labels | Roboto; .76rem/.16em uppercase blue eyebrow where the source uses it. | Source eyebrow and navbar. Roboto Mono is for code and useful numerical work, not ordinary status/folder labels. |
+| Reading | Bounded 760px editorial measure with source hierarchy. Supporting facts can have their own region. | Page layout and editorial CSS. An accent rail/mono label is not mandatory article anatomy. |
+| Desktop navbar | Navy rgba(6,19,37,.84), .4rem radius, white 20% border, 14px blur, source navbar shadow. | Source site-navbar. Docs retains a contained in-flow variant because there is no photographic masthead. |
+| Desktop popup | White surface, ink text, ice hover; 15rem min width; .55rem padding; .3rem radius; source rule and `0 18px 44px rgba(6,19,37,.18)` shadow; white 12px pointer. | Source dropdown and live observation. The light surface is independent of the dark parent and full-page mode. |
+| Popup item | .9rem/1.65 Roboto; .62rem/.7rem padding; small item radius. | Source dropdown-item. Use source SVG chevron. |
+| Mobile navigation | Collapsed Menu below 992px; submenu static/indented/transparent on navy; no popup pointer, border or shadow. | Source mobile overrides. Do not impose desktop popup styling here. |
+| Navigation behavior | Native details retains click/Enter/Space and exclusive groups; Escape restores summary, blur closes; mobile Menu Escape restores trigger. | Explicit implementation translation of source dropdown capability. Hover is visual feedback, not the only access route. |
+| Search | Source field material, label and underline retained. Docs uses an explicitly labelled live component filter rather than site-wide GET search. | Source site-search visual role; task-specific documentation extension. |
+| Primary action | Navy with blue hover in light mode; .75rem bold uppercase UI type, .035em tracking, .625rem/1.5rem padding. | Observed source navy button and foundation dimensions. Dark mode uses semantic contrast roles. |
+| Input | Native control and own small radius, theme/source padding; keep visible labels. | Source control vocabulary; site-search is not the default general form geometry. |
+| Table | .95rem UI type, .85rem/.7rem cells, top alignment, source rule; no arbitrary compact-family default. | Editorial source table. Explicit compact density remains future task-specific work. |
+| Quote | 4px blue leading rule, Slab quotation text. | Editorial blockquote. |
+| Footer | Navy identity column spanning two tracks, four link groups, and a separate ownership/contact base line; 5rem/1.5rem vertical padding, 48px desktop gap. | SiteFooter/site.css. The adopting host owns identities, organizations and destinations. |
+
+## Explicit application extensions
+
+AppShell is an application frame, not the entire origin website. Both languages support top, side and none. The existing Krigsvold default side frame is retained for compatibility with the workbench; it is not a grammar requirement. The hard-coded rail colophon is removed.
+
+No origin object establishes a universal Krigsvold TOC. The experimental index/inline extension uses native fragment navigation, unnumbered depth-aware hierarchy and reading order before body. A persistent rail appears only when the available width supports it. No invented accent top rule or mono eyebrow is required. DefinitionList supports rows, stack and grid in either family; source fellow facts already demonstrate stacking.
+
+Task dialogs, validation summaries, notices, badges, switches, tabs, file controls and controlled result paging are explicit new application objects. They preserve native semantics, visible focus, clear labels and recoverable operations. ErrorSummary uses a leading severity rule, consistent with its task rather than a forced opposite Martlet treatment. Tabs use a selected underline, not an invented filled institutional badge. Invalid styling means `aria-invalid="true"`, never mere attribute presence.
+
+Field/group/region roles are .5/1.5/3rem source-scale values with experimental relational assignments. Local density serves comparison; generous source page section spacing remains a different role. A 3px selection edge explains the current note, while nonnumeric status/folder labels use Roboto. The results/detail composition is a task choice, not compulsory Krigsvold anatomy.
+
+Dark mode keeps the source object hierarchy and existing semantic contrast roles. The source desktop navbar popup remains light; mobile remains transparent on navy. New status/error/switch surfaces are application extensions and need state/contrast evidence. Code keeps theme roles pending a matched origin code specimen review.
+
+## Boundary and evidence
+
+The theme-site crystal is the existing system mark used by documentation. It does not replace an adopting application's own identity or the origin institution's snowflake badge. Docs preview, finder, copy/download controls, simulated failure and session-only notes are host tooling.
+
+Polar imagery, title/arms, award content, legal policy and analytics remain host responsibilities. Origin masthead, evidence/fellow/card/figure/FAQ variants outside the current 22 exports remain named vocabulary gaps, not silently shipped components. Full accessibility, RTL/localization and sustained-use evidence remain open. Read this profile with the grammar/API references; catalogue hashes do not ratify design choices.
+
+## Framework consolidation
+
+Core 2.2.0 and Astro 1.2.0 are unreleased candidates. The source profile is an opt-in import and class; existing core defaults and existing Astro slots remain compatible. New TableOfContents and grouped SiteFooter anatomy are available in the paired candidate packages. React 0.1.0 retains its existing theme 2.1.0 dependency and React-specific events and focus contracts. Framework support is recorded in language.json. These additions do not make the grammar stable.
+
+## Grammar review 0.3
+
+Validated forms and queried results add explicit application contracts for grouping, action scope, committed versus draft queries, current-page selection and modal recovery. These are experimental extensions, with separate family composition choices and shared native behavior. No original palette, mark, header direction or existing component default changes. Read docs/coverage.md and docs/patterns/ for the bounded evidence and remaining vocabulary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krigsvold/theme",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,12 @@
     "./design.json": "./dist/design.json",
     "./capabilities.json": "./dist/capabilities.json",
     "./package.json": "./package.json",
-    "./legacy.css": "./dist/legacy.css"
+    "./legacy.css": "./dist/legacy.css",
+    "./layout.css": "./dist/layout.css",
+    "./layout.json": "./dist/layout.json",
+    "./patterns.css": "./dist/patterns.css",
+    "./source-profile.css": "./dist/source-profile.css",
+    "./language.json": "./dist/language.json"
   },
   "publishConfig": {
     "access": "public"