layout-style-css 1.1.2 → 2.0.0

package/docs/wiki/Migrating-To-2.0.md

@@ -0,0 +1,186 @@
+# Migrating To 2.0
+
+Version 2.0 rebuilds Layout Style CSS as a container-first, dependency-free structural layout system. This guide maps the complete 1.x public surface to v2 and identifies the compatibility window.
+
+## Runtime And Tooling Contract
+
+- Development and release scripts require Node.js 20 or newer.
+- The package has no runtime dependencies and no peer dependencies.
+- `ui-style-kit-css@2.0.1` and `interactive-surface-css@1.4.0` are exact development and integration fixtures, not consumer dependencies.
+- Current evergreen Chromium, Firefox, and WebKit are supported.
+- Responsive recipes use core thresholds at `48rem` and `64rem`; personalities may add personality-specific thresholds.
+
+Install companions explicitly only when the application uses them:
+
+```bash
+npm install layout-style-css@2.0.0
+npm install ui-style-kit-css@2.0.1 interactive-surface-css@1.4.0
+```
+
+The upcoming UI Style Kit revision is a separate follow-up, not part of the Layout Style CSS 2.0 release.
+
+## Export Changes
+
+The v2 package exports are focused and companion-free:
+
+| V2 import | Purpose |
+| --- | --- |
+| `layout-style-css` | Default full bundle: core plus all personalities. |
+| `layout-style-css/min.css` | Minified full bundle. |
+| `layout-style-css/core.css` | Wrappers, primitives, recipes, and utilities. |
+| `layout-style-css/wrappers.css` | Tokens, reset, safe-area gutters, and wrappers. |
+| `layout-style-css/primitives.css` | Composition primitives. |
+| `layout-style-css/recipes.css` | Functional recipes and named areas. |
+| `layout-style-css/utilities.css` | Structural and order utilities. |
+| `layout-style-css/personalities.css` | All personalities. |
+| `layout-style-css/personalities/minimal-saas.css` | One personality; replace the filename with any of the sixteen names. |
+| `layout-style-css/integrations/ui-style-kit.css` | Import-free UI Style Kit structural bridge. |
+| `layout-style-css/legacy.css` | Full v2 bundle plus v1 selector aliases. |
+
+The following v1 exports were removed from the default contract:
+
+- `layout-style-css/base.css` and the old `layout-base.css` dist file
+- `layout-style-css/bridge.css` and `layout-ui-style-kit-bridge.css`
+- `layout-style-css/all.css`
+- `layout-style-css/all-with-ui-kit.css`
+- `layout-style-css/all-with-ui-kit-and-interactive-surface.css`
+- duplicated root personality exports such as `layout-style-css/minimal-saas.css`
+- root dist files named `layout-style-*.css`
+
+Replace a root personality import with its `personalities/` path. Replace old aggregates with explicit companion imports and the v2 default or focused core.
+
+## Import Recipes
+
+Standalone Layout Style CSS:
+
+```js
+import "layout-style-css";
+```
+
+Layout plus UI Style Kit:
+
+```js
+import "ui-style-kit-css/with-bridge.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+All three libraries must be imported in this exact order:
+
+```js
+import "ui-style-kit-css/with-bridge.css";
+import "interactive-surface-css/state-core.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+The first layer supplies UI paint, the second interaction states, the third structural name mappings, and the fourth the layout system. The Layout integration file contains no package imports.
+
+## Wrapper Mapping
+
+V2 wrapper names communicate intent rather than a generic size tier. `.ly-wrapper` now defaults to the `72rem` content measure and establishes an inline-size container. A personality may change that plain-wrapper default, but an explicit compact, prose, content, wide, full, or breakout variant always wins.
+
+| 1.x selector | V2 selector | V2 measure or behavior |
+| --- | --- | --- |
+| `.ly-container`, `.ly-wrapper` | `.ly-wrapper` or `.ly-wrapper--content` | Default `72rem` content wrapper |
+| `.ly-container--sm`, `.ly-wrapper--sm` | `.ly-wrapper--compact` | `40rem` |
+| `.ly-container--md`, `.ly-wrapper--md` | Local `--ly-wrapper-max: 56rem` override, or temporary `legacy.css` | No canonical v2 tier |
+| `.ly-wrapper--readable` | `.ly-wrapper--prose` | `68ch` |
+| `.ly-container--lg`, `.ly-wrapper--lg` | `.ly-wrapper--content` | `72rem` |
+| `.ly-container--xl`, `.ly-wrapper--xl` | `.ly-wrapper--wide` | `112rem` in the new semantic scale |
+| `.ly-container--wide`, `.ly-wrapper--wide` | `.ly-wrapper--wide` | `112rem` |
+| `.ly-container--fluid`, `.ly-wrapper--fluid` | `.ly-wrapper--full` | Full available width with safe-area gutters |
+| No v1 equivalent | `.ly-wrapper--breakout` | Content, feature, and full-width lanes |
+
+The v1 medium `56rem` and extra-large `88rem` measures do not have canonical v2 names. Use a local `--ly-wrapper-max` override if those exact measures are product requirements, or load `legacy.css` while migrating.
+
+Breakout markup defaults to the content lane:
+
+```html
+<div class="ly-wrapper ly-wrapper--breakout">
+  <article data-ly-lane="content">Article</article>
+  <figure data-ly-lane="feature">Feature media</figure>
+  <section data-ly-lane="full">Full-width stage</section>
+</div>
+```
+
+Every wrapper uses fluid logical gutters and safe-area insets. Test the containing element around the `48rem` and `64rem` core thresholds and around any selected personality threshold; viewport width alone no longer determines layout changes.
+
+## Canonical Hooks
+
+V2 standardizes three attributes:
+
+- `data-ly-layout` selects one of the sixteen personalities.
+- `data-ly-recipe` identifies `app-shell`, `dashboard`, `docs`, `list-detail`, `split-hero`, `gallery`, or `card-grid`.
+- `data-ly-area` identifies `header`, `nav`, `main`, `aside`, `footer`, `content`, `media`, `actions`, `primary`, or `secondary`.
+
+Every `data-ly-recipe` value is a complete alternative to its matching recipe class. For example, `data-ly-recipe="dashboard"` works without `.ly-dashboard`; applications may keep the class API, use the attribute API, or include both during migration.
+
+```html
+<body class="ly-root" data-ly-layout="minimal-saas">
+  <div class="ly-dashboard" data-ly-recipe="dashboard">
+    <header data-ly-area="header">Header</header>
+    <nav data-ly-area="nav">Navigation</nav>
+    <main data-ly-area="main">Main</main>
+    <aside data-ly-area="aside">Aside</aside>
+    <footer data-ly-area="footer">Footer</footer>
+  </div>
+</body>
+```
+
+The v1 personality hooks `data-layout`, `layout-style`, `.ly-layout-*`, and `.ly-style-*` are legacy-only. Move the personality value to `data-ly-layout` on `.ly-root`.
+
+## Primitive And Recipe Mapping
+
+The v2 composition set is stack, cluster, center, cover, switcher, sidebar, grid, split, panes, media, reel, frame, and bounded scroll.
+
+| 1.x API | V2 API |
+| --- | --- |
+| `.ly-row` plus `.ly-col-*` | `.ly-grid` plus `.ly-cols-*` and `.ly-span-*`, or `.ly-cluster` for wrapping flow |
+| `.ly-carousel` | `.ly-reel` |
+| `.ly-scroll-area` | `.ly-scroll` |
+| `.ly-sidebar-layout` | `.ly-sidebar` or the `docs` recipe |
+| `.ly-panes--two` | `.ly-panes--2` |
+| `.ly-panes--three` | `.ly-panes--3` |
+| Ad hoc shell class combinations | A matching `data-ly-recipe` root with named `data-ly-area` children |
+| `.ly-button-group` | `.ly-cluster` |
+| `.ly-card-grid` | `data-ly-recipe="card-grid"` or `.ly-card-grid` |
+| `.ly-gallery` | `data-ly-recipe="gallery"` or `.ly-gallery` |
+| `.ly-content` | V2 primitives and recipe areas already apply shrink safety; `legacy.css` preserves the structural `min-inline-size: 0` alias for ad hoc v1 content regions. |
+| `.ly-divider` | Replace spacing with a stack gap or spacing utility and source the visual divider from UI Style Kit or the application theme. `legacy.css` preserves only its `1px` minimum block geometry and block spacing, never paint. |
+| `.ly-surface--raised` | Removed. Raised radius, border, background, and shadow treatment belongs to UI Style Kit or application theme styling, so `legacy.css` intentionally does not restore this selector. |
+
+The v1 column, carousel, button-group, sidebar, pane, card-size, app-area, scroll, content, and structural divider aliases remain functional only through `legacy.css`. The paint-owned `.ly-surface--raised` API is removed rather than aliased.
+
+## Mobile Order And Accessibility
+
+DOM order is authoritative on mobile and must match the intended reading order and focus order. Built-in recipes never use CSS `order`; they rearrange named grid areas at wider containers without changing source order.
+
+V2 provides `.ly-order-first`, `.ly-order-normal`, `.ly-order-last`, and `.ly-order-1` through `.ly-order-6`. Equivalent `ly-md-order-*` and `ly-lg-order-*` utilities activate at the `48rem` and `64rem` container thresholds.
+
+These utilities are explicit escape hatches. They can make visual order disagree with assistive-technology reading order or keyboard focus order. Prefer semantic source order. When an escape hatch is unavoidable, test the complete keyboard sequence, screen-reader reading order, and mobile fallback.
+
+## Temporary Legacy Bundle
+
+Use one import during an incremental migration:
+
+```js
+import "layout-style-css/legacy.css";
+```
+
+`legacy.css` imports the full v2 bundle and adds functional aliases for old wrapper names, root hooks, layout aliases, 12-column utilities, carousel, button groups, sidebar layouts, pane names, card sizing, app regions, scroll areas, `.ly-content`, and structural `.ly-divider` geometry. It does not restore `.ly-surface--raised`, companion imports, or removed package exports.
+
+Legacy compatibility is supported for the v2 line only and is scheduled for removal in v3. Treat it as a transition tool: migrate markup and imports before upgrading to the next major version.
+
+## Migration Checklist
+
+1. Upgrade the development runtime to Node.js 20 or newer.
+2. Remove companion packages from peer assumptions and install only the layers the application uses.
+3. Replace removed aggregate and root personality imports with focused v2 exports.
+4. Change wrapper size names to semantic wrapper names.
+5. Move personality selection to `data-ly-layout`.
+6. Add `data-ly-recipe` and `data-ly-area` hooks while preserving correct mobile source order.
+7. Replace v1 column and recipe aliases, or temporarily switch to `legacy.css`.
+8. Audit every base, `ly-md-*`, and `ly-lg-*` order utility for reading and focus-order impact.
+9. Test below and above both core container thresholds and the selected personality threshold in Chromium, Firefox, and WebKit.
+10. Remove `legacy.css` before the v3 upgrade.

package/docs/wiki/Release-And-Publishing.md

@@ -1,69 +1,75 @@
-# Release And Publishing
-
-This page is the release checklist for `layout-style-css@1.1.2`.
-
-## Version Contract
-
-- `package.json` version is `1.1.2`.
-- `package-lock.json` is synchronized with `1.1.2`.
-- `CHANGELOG.md` contains a `1.1.2` entry.
-- README and wiki docs link to the current public API.
-
-## Verification
-
-Run:
-
-```bash
-npm run build
-npm run lint
-npm test
-npm run check
-npm run release:verify
-npm audit --audit-level=moderate
-git diff --check
-```
-
-Expected result: every command exits with status `0`. `git diff --check` may print line-ending warnings on Windows, but it must not report whitespace errors.
-
-## Publish
-
-Before publishing, confirm npm does not already have the target version:
-
-```bash
-npm view layout-style-css@1.1.2 version --json
-```
-
-Publish:
-
-```bash
-npm login
-npm publish --access public
-```
-
-Verify:
-
-```bash
-npm view layout-style-css@1.1.2
-```
-
-## Tag
-
-Tag the release:
-
-```bash
-git tag v1.1.2
-git push origin v1.1.2
-```
-
-The npm publish workflow runs when the `v1.1.2` GitHub release is published. If the release event needs to be replayed, run the `Node.js Package` workflow manually from the default branch with `release_tag` set to `v1.1.2`.
-
-## GitHub Wiki Mirror
-
-If the repository wiki is enabled, mirror `docs/wiki/*.md` into:
-
-```txt
-https://github.com/Foscat/Layout-Style-CSS.wiki.git
-```
-
-The wiki remote was not available during local preparation, so the versioned source remains the authoritative documentation until the remote is initialized.
-
+# Release And Publishing
+
+This checklist prepares `layout-style-css@2.0.0`. Publishing, tagging, pushing, and creating a GitHub release require separate explicit approval.
+
+## Version Contract
+
+- `package.json` and `package-lock.json` identify `2.0.0`.
+- Node.js 20 and 22 pass standalone CI.
+- `CHANGELOG.md` contains the dated breaking-release entry.
+- README, migration guide, wiki, demo, exports, and tarball describe the same v2 API.
+- No peer or runtime dependencies are present.
+
+## Local Verification
+
+Install all Playwright engines once:
+
+```bash
+npx playwright install chromium firefox webkit
+```
+
+Then run:
+
+```bash
+npm run build
+npm run lint
+npm run check:demo-js
+npm run test:static
+npm run test:demo:quick
+npm run test:demo:all
+npm run test:pages
+npm run pack:dry-run
+npm run release:verify
+git diff --check
+```
+
+`release:verify` runs build, lint, JavaScript syntax, static contracts, the Pages artifact, Chromium, Firefox, WebKit, the intentional tarball listing, `npm audit --audit-level=moderate`, and an npm publish dry run. It does not publish.
+
+## Tag And Version Validation
+
+The publish workflow checks out the selected tag and fails unless it equals `v${package.version}`. For this release the only valid tag is `v2.0.0`.
+
+After separate approval, an operator may check registry availability:
+
+```bash
+npm view layout-style-css@2.0.0 version --json
+```
+
+The eventual release sequence is:
+
+```bash
+git tag v2.0.0
+git push origin v2.0.0
+```
+
+Publishing the `v2.0.0` GitHub release triggers the npm workflow. A separately approved recovery run may use `release_tag` set to `v2.0.0`.
+
+## Workflow Safety
+
+Create a GitHub Environment named `npm` and configure required reviewers before enabling the publish job. Environment approval is the final human authorization boundary for npm releases.
+
+Before `npm ci` can execute package lifecycle code, the workflow:
+
+1. rejects release inputs that are not strict `v`-prefixed semantic-version tags;
+2. checks out the exact `refs/tags/<release_tag>` namespace without persisted credentials;
+3. verifies `HEAD` equals the tag's peeled commit;
+4. fetches `origin/main` and requires the tag commit to be reachable from protected main; and
+5. requires the package version to equal the tag.
+
+The workflow installs Chromium, Firefox, and WebKit, runs full release verification, and publishes with npm provenance. `NODE_AUTH_TOKEN` exists only on the final publish step. Migrating to npm trusted publishing should remove that long-lived secret in a follow-up.
+
+The workflow actions remain major-version references. Pinning every third-party action to an immutable commit SHA is a documented security follow-up and should be performed with an automated update process. Do not bypass a failed trust, version, browser, audit, tarball, or documentation contract.
+
+## Wiki Mirror
+
+The versioned `docs/wiki/` source is authoritative. If GitHub Wiki is enabled, mirror these Markdown files only after the release documentation has passed the local contract suite.

package/docs/wiki/Security-And-Support.md

@@ -1,34 +1,36 @@
-# Security And Support
-
-`layout-style-css` is a CSS-only package. The package does not execute runtime JavaScript, call external services, read secrets, or process user input.
-
-## Supported Versions
-
-| Version | Supported |
-| --- | --- |
-| `1.1.x` | Yes |
-| `1.0.x` | Security fixes only when practical |
-
-## Report A Security Issue
-
-Use GitHub security advisories when available. If advisories are not enabled, open a minimal GitHub issue that requests a private coordination path and avoids public exploit details.
-
-Include:
-
-- affected version
-- affected package export or CSS selector
-- reproduction steps
-- expected impact
-- whether the issue affects package consumers, the demo, or GitHub Pages deployment
-
-## Security Checks
-
-Before release:
-
-```bash
-npm audit --audit-level=moderate
-npm run release:verify
-```
-
-The package contract tests check package exports, README import examples, npm tarball contents, generated CSS, demo smoke behavior, and GitHub Pages artifact structure.
-
+# Security And Support
+
+`layout-style-css` is dependency-free runtime CSS. It executes no consumer JavaScript, calls no services, reads no secrets, and processes no user input. The demo JavaScript uses allowlisted query values and `textContent` for generated snippets.
+
+## Supported Versions
+
+| Version | Supported |
+| --- | --- |
+| `2.x` | Yes |
+| `1.1.x` | Migration support only |
+| `1.0.x` | No |
+
+The v2 `legacy.css` compatibility bundle is scheduled for removal in v3.
+
+## Browser Baseline
+
+Current evergreen Chromium, Firefox, and WebKit are supported. The mobile DOM-order fallback remains usable when container queries are unavailable, but current browser engines are the tested contract.
+
+## Report A Security Issue
+
+Use GitHub security advisories when available. Otherwise, open a minimal issue requesting a private coordination path without publishing exploit details.
+
+Include the affected version, export or selector, reproduction, expected impact, and whether the issue affects package consumers, the demo, or GitHub Pages.
+
+## Release Checks
+
+```bash
+npm audit --audit-level=moderate
+npm run release:verify
+```
+
+The release gate checks authored/generated parity, structural ownership, documentation, tarball contents, Pages output, and the Chromium, Firefox, and WebKit rendered matrices.
+
+The npm publish workflow also enforces a strict tag namespace, exact tag/HEAD identity, protected-main ancestry, package-version alignment, an `npm` GitHub Environment with required reviewers, and npm provenance. The registry token is scoped to the final publish step. Replacing it with npm trusted publishing and pinning GitHub Actions to an immutable commit SHA remain explicit hardening follow-ups.
+
+The demo protects its two exact-version companion CDN fixtures with SHA-384 subresource integrity and anonymous CORS; rendered tests recompute those hashes from the pinned local fixtures.

package/docs/wiki/UI-Style-Kit-Compatibility.md

@@ -1,54 +1,50 @@
-# UI Style Kit Compatibility
-
-`layout-style-css` is built to pair with `ui-style-kit-css@2.0.1` while keeping each package responsible for one layer.
-
-## Ownership Boundary
-
-| Package | Owns |
-| --- | --- |
-| `ui-style-kit-css` | colors, typography, borders, shadows, native controls, component paint, focus states, themes, modes |
-| `layout-style-css` | wrappers, shells, grid behavior, panes, sidebars, spacing, layout recipes, layout personalities |
-
-## One Import Pairing
-
-```js
-import "layout-style-css/all-with-ui-kit.css";
-```
-
-This imports UI Style Kit and all layout files. Use `layout-style-css/all-with-ui-kit-and-interactive-surface.css` when Interactive Surface is also required.
-
-## Prefix Aliases
-
-The bridge maps UI-style structural names to layout primitives for these prefixes:
-
-```txt
-saas, bento, max, bau, tactile, neo, retro, brutal, cyber, y2k, rg
-```
-
-| Alias pattern | Layout primitive |
-| --- | --- |
-| `<prefix>-container` | `.ly-wrapper` |
-| `<prefix>-section` | `.ly-section` |
-| `<prefix>-stack` | `.ly-stack` |
-| `<prefix>-cluster` | `.ly-cluster` |
-| `<prefix>-grid` | `.ly-grid` |
-| `<prefix>-split` | `.ly-split` |
-| `<prefix>-button-group` | `.ly-button-group` |
-| `<prefix>-card-grid` | `.ly-card-grid` |
-| `<prefix>-card-sm`, `<prefix>-card-md`, `<prefix>-card-lg` | `.ly-card-sm`, `.ly-card-md`, `.ly-card-lg` |
-| `<prefix>-gallery` | `.ly-gallery` |
-| `<prefix>-carousel` | `.ly-carousel` |
-
-Visual component aliases such as `<prefix>-button`, `<prefix>-card`, and `<prefix>-panel` remain owned by UI Style Kit.
-
-## Integration Example
-
-```html
-<section class="saas-container saas-section">
-  <div class="saas-card-grid">
-    <article class="saas-card saas-card-md">Plan</article>
-    <article class="saas-card saas-card-md">Plan</article>
-  </div>
-</section>
-```
-
+# UI Style Kit Compatibility
+
+Layout Style CSS is dependency-free. `ui-style-kit-css@2.0.1` is an exact development fixture used to verify the optional bridge; it is not a runtime or peer dependency. The UI Style Kit revision is a follow-up, not part of this release.
+
+## Ownership Boundary
+
+| Package | Owns |
+| --- | --- |
+| `layout-style-css` | Wrappers, containment, flow, areas, grids, spans, recipes, and spatial personalities. |
+| `ui-style-kit-css` | Color, typography, borders, shadows, native controls, component paint, themes, and modes. |
+| `interactive-surface-css` | Interaction-state styling. |
+
+## Explicit Imports
+
+Layout plus UI:
+
+```js
+import "ui-style-kit-css/with-bridge.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+All three libraries:
+
+```js
+import "ui-style-kit-css/with-bridge.css";
+import "interactive-surface-css/state-core.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+The Layout integration bridge contains structural mappings but no package imports. The removed `all-with-ui-kit*` aggregates have no v2 replacement because dependency ownership stays with the application.
+
+## Structural Aliases
+
+The bridge supports the `saas`, `bento`, `max`, `bau`, `tactile`, `neo`, `retro`, `brutal`, `cyber`, `y2k`, and `rg` prefixes for container, section, stack, cluster, grid, split, button-group, card-grid, card-size, gallery, and carousel structure.
+
+Visual component names remain owned by UI Style Kit. The bridge does not map color, typography, border, shadow, theme, or interaction tokens.
+
+The removed v1 `.ly-surface--raised` selector is not restored by `legacy.css`; its radius and raised paint belong to UI Style Kit or application theme styling. Likewise, the legacy `.ly-divider` alias supplies structural size and spacing only, leaving the visible separator to the UI layer.
+
+## Compatibility Baseline
+
+| Library | Verified fixture | Consumer requirement |
+| --- | --- | --- |
+| Layout Style CSS | `2.0.0` | Required for this API |
+| UI Style Kit CSS | `2.0.1` | Optional |
+| Interactive Surface CSS | `1.4.0` `state-core.css` | Optional |
+
+Current evergreen Chromium, Firefox, and WebKit are covered by the release gate.

package/docs/wiki/_Sidebar.md

@@ -1,14 +1,15 @@
-# Wiki Navigation
-
-- [Home](Home.md)
-- [Getting Started](Getting-Started.md)
-- [Installation And CDN](Installation-And-CDN.md)
-- [Layout Primitives](Layout-Primitives.md)
-- [Layout Recipes](Layout-Recipes.md)
-- [Layout Styles](Layout-Styles.md)
-- [UI Style Kit Compatibility](UI-Style-Kit-Compatibility.md)
-- [Demo And GitHub Pages](Demo-And-GitHub-Pages.md)
-- [Release And Publishing](Release-And-Publishing.md)
-- [Security And Support](Security-And-Support.md)
-- [Contributing](Contributing.md)
-
+# Wiki Navigation
+
+- [Home](Home.md)
+- [Getting Started](Getting-Started.md)
+- [Installation And CDN](Installation-And-CDN.md)
+- [Layout Primitives](Layout-Primitives.md)
+- [Layout Recipes](Layout-Recipes.md)
+- [Layout Styles](Layout-Styles.md)
+- [UI Style Kit Compatibility](UI-Style-Kit-Compatibility.md)
+- [Migrating To 2.0](Migrating-To-2.0.md)
+- [Demo And GitHub Pages](Demo-And-GitHub-Pages.md)
+- [Release And Publishing](Release-And-Publishing.md)
+- [Security And Support](Security-And-Support.md)
+- [Contributing](Contributing.md)
+