@kerfjs/ui 5.0.0-beta.33 → 5.0.0-beta.35

package/docs/component-selection.md

@@ -38,7 +38,7 @@ foreground/background contrast relationships and visible focus ring.
 
 ### Typed runtime dimensions
 
-Use `List` spacing shorthands for the common case: `gap="xs"`, `gap="m"`, and
+Use `Row` or `List` spacing shorthands for the common case: `gap="xs"`, `gap="m"`, and
 the other `UiSpaceName` values resolve to their matching `--kui-space-*` token.
 The canonical rhythm is `none`, `2xs`, `xs`, `m`, and `l`; use `s` and `xl`
 only as deliberate exceptions.
@@ -47,24 +47,26 @@ When a value cannot be expressed by one spacing step, import the CSS-free
 `@kerfjs/ui/css-values` subpath. `px`, `rem`, `em`, and `pct` create typed
 `CssLength` values; `space` and `lengthVar` reference spacing or
 application-owned length tokens. `plus` creates a non-standalone
-`CssLengthExpression`, so wrap it with `calc` before passing it to `List.gap`:
+`CssLengthExpression`, so wrap it with `calc` before passing it to a gap prop:
 
 ```tsx
 import { calc, pct, plus, rem, space } from "@kerfjs/ui/css-values";
 import { List } from "@kerfjs/ui/list";
+import { Row } from "@kerfjs/ui/row";
 
 <List gap="xs">...</List>;
+<Row hAlign="full" vAlign="middle" gap="m">...</Row>;
 <List gap={space("m")}>...</List>;
 <List gap={calc(plus(rem(0.25), pct(10)))}>...</List>;
 ```
 
 `CssValue` is the common branded base, not an arbitrary-string constructor.
-Raw strings such as `"0.25rem"` no longer satisfy `List.gap`; this breaking
+Raw strings such as `"0.25rem"` no longer satisfy `Row.gap` or `List.gap`; this breaking
 contract lands before the 5.0 stable release so misspelled tokens and incomplete
 expressions fail during typechecking rather than in the browser.
 
 Other CSS-valued props use distinct contracts: `flex()` creates `CssFlex` for
-`List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
+`Row.flex` and `List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
 keywords for width/height); and `uiColor()`/`colorVar()` create `CssColor` for
 `SelectChoice.color`. Do not substitute one brand for another. Row components
 have no declaration-string `style` prop; use `className`, documented public

package/docs/layout.md

@@ -112,12 +112,37 @@ The two relationships that get confused most are 8px vs 24px: 8px is _inside_ a
 group, 24px is _between_ major, differing regions. 16px sits between them for
 same-kind groups.
 
-For `List.gap`, pass these token names directly (`gap="xs"`, `gap="m"`) or use
+For `Row.gap` and `List.gap`, pass these token names directly (`gap="xs"`, `gap="m"`) or use
 `space('xs')` from `@kerfjs/ui/css-values` when composing a value in JavaScript.
 Use `rem`, `em`, `px`, `pct`, `lengthVar`, and `calc(plus(...))` only when a
 named spacing relationship does not express the requirement; do not pass raw
 CSS strings.
 
+## Row and List alignment
+
+Use `Row` for a horizontal flex layout and `List` for a vertical one. `Row`
+defaults to `hAlign="left"`, `vAlign="full"`, `gap="xs"`, and no wrapping;
+`List` retains its existing full-width, top-aligned defaults and zero gap.
+Both components accept the same physical-axis vocabulary:
+
+| Axis       | Values and aliases                                                                                                             | Flex behavior                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Horizontal | `left` / `l` / `flex-start`; `center` / `c` / `space-around`; `right` / `r` / `flex-end`; `full` / `f` / `space-between`       | Distributes a Row's children; aligns a List's children across its width.  |
+| Vertical   | `top` / `t` / `flex-start`; `middle` / `m` / `c` / `space-around`; `bottom` / `b` / `flex-end`; `full` / `f` / `space-between` | Aligns a Row's children across its height; distributes a List's children. |
+
+Cross-axis `space-around` and `space-between` are not valid `align-items`
+values. Kerf therefore maps `middle` to centered items and `full` to stretched
+items, while applying the requested distribution to `align-content` when a
+Row wraps. Prefer the descriptive values in application code; the short and
+CSS-shaped aliases are provided for compact or migrated call sites.
+
+`Row.flex` and `List.flex` share one typed participation contract. Omit the prop
+for the CSS initial value, pass `true` for `1 1 auto`, select the finite
+`"none"`, `"auto"`, or `"initial"` keyword, or use
+`flex(grow, shrink, basis)` from `@kerfjs/ui/css-values` for a complete branded
+shorthand. A `CssLength` is not a flex shorthand, and arbitrary strings are
+rejected by the type contract.
+
 `--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the
 canonical rhythm** — reach for them only as a deliberate exception, never as a
 default step. Prefer the five canonical tokens so spacing stays legible and

package/docs/ux-demo.md

@@ -2,6 +2,16 @@
 
 Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
 
+Every Playwright entry point builds current source before the preview server
+starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused
+`npx playwright test tests/browser/row.spec.ts` both run catalog generation and
+demo-conformance preflights, build the package and production catalog, then
+launch Chromium, Firefox, and WebKit. The build emits
+`source-freshness.json`; browser coverage compares it with an independent hash
+of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
+after a route or component edit. `npm run demo:serve` remains a preview-only
+command for an already-built catalog.
+
 Seven lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).

package/llms.txt

@@ -91,7 +91,10 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
-- **Use `List` for vertical layout.** It supplies a stretch-aligned column plus
+- **Use `Row` for horizontal and `List` for vertical layout.** Both expose
+  physical `hAlign`/`vAlign` props and typed gaps. Row defaults to left/full,
+  an `xs` gap, and no wrapping; List retains full/top and zero-gap defaults.
+  List additionally supplies
   optional typed `gap`, `flex`, vertical scrolling, and canonical
   `dividerSides` (`t`/`r`/`b`/`l` order). It adds no list semantics; children own
   those, and only one bounded region should own scrolling. Pass a finite spacing
@@ -154,7 +157,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
-  regions). 12px/32px are off-scale exceptions. Prefer direct `List.gap`
+  regions). 12px/32px are off-scale exceptions. Prefer direct `Row.gap`/`List.gap`
   shorthands; use `space`, `px`, `rem`, `em`, `pct`, `lengthVar`, and
   `calc(plus(...))` for typed runtime composition. `remify()` is source-CSS only.
 - **Keep nested highlight corners concentric.** Inset hover and selection surfaces

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.33",
+  "version": "5.0.0-beta.35",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -88,6 +88,11 @@
       "browser": "./dist/browser/list.js",
       "import": "./dist/list.js"
     },
+    "./row": {
+      "types": "./dist/row.d.ts",
+      "browser": "./dist/browser/row.js",
+      "import": "./dist/row.js"
+    },
     "./list-action-row": {
       "types": "./dist/list-action-row.d.ts",
       "browser": "./dist/browser/list-action-row.js",
@@ -278,6 +283,7 @@
     "./floating-toolbar.css": "./dist/styles/floating-toolbar.css",
     "./toolbar-text.css": "./dist/styles/toolbar-text.css",
     "./list.css": "./dist/styles/list.css",
+    "./row.css": "./dist/styles/row.css",
     "./list-action-row.css": "./dist/styles/list-action-row.css",
     "./list-item.css": "./dist/styles/list-item.css",
     "./list-header.css": "./dist/styles/list-header.css",
@@ -323,11 +329,15 @@
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
     "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
+    "test:e2e:serve": "npm run check:catalog && npm run check:demo-conformance && npm run demo:build && npm run demo:serve",
     "format": "prettier --write . --ignore-unknown",
     "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
     "check:format": "prettier --check . --ignore-unknown",
     "catalog:sync": "node scripts/sync-component-catalog.mjs && node scripts/sync-component-catalog-v2.mjs",
     "catalog:v2:sync": "node scripts/sync-component-catalog-v2.mjs",
+    "check:component-integrations": "node scripts/check-component-integrations.mjs",
+    "component-integrations:dry-run": "node scripts/check-component-integrations.mjs --dry-run",
+    "check:change": "node scripts/check-ui-change.mjs",
     "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/sync-component-catalog-v2.mjs --check && node scripts/check-component-catalog.mjs",
     "check:profile": "node scripts/check-application-ui-profile.mjs",
     "check:demo-conformance": "node scripts/check-catalog-demo-conformance.mjs",
@@ -335,6 +345,8 @@
     "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs && node scripts/audit-ai-regression-results-v3.mjs",
     "check:ai-signatures": "node scripts/sync-ai-public-signatures.mjs --check",
     "ai:signatures:sync": "npm run build && node scripts/sync-ai-public-signatures.mjs",
+    "check:ai-compatibility": "node scripts/sync-ai-compatibility.mjs",
+    "ai:compatibility:sync": "node scripts/sync-ai-compatibility.mjs --write",
     "ai:regressions:compile": "node scripts/compile-ai-regression-response.mjs",
     "ai:regressions:prepare": "node scripts/prepare-ai-regression.mjs",
     "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
@@ -354,8 +366,8 @@
     "test:contract-types:source": "node node_modules/typescript7/bin/tsc -p tests/consumer-types/contracts/tsconfig.source.json",
     "test:contract-types:packed": "node scripts/check-packed-type-contracts.mjs",
     "test:consumer-types": "npm run test:contract-types:source && npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json && npm run test:contract-types:packed",
-    "test:e2e": "npm run demo:build && playwright test",
-    "check": "npm run check:catalog && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
+    "test:e2e": "playwright test",
+    "check": "npm run check:catalog && npm run check:component-integrations && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:guidance && npm run check:ai-compatibility && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
     "prepublishOnly": "npm run check",
     "check:design-templates": "node scripts/check-design-templates.mjs",
     "check:design-templates:drift": "node scripts/check-design-templates-drift.mjs",

package/dist/chunk-RL6COPKF.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/list.tsx"],"names":[],"mappings":";;;AAUA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAgBO,SAAS,IAAA,CAAK;AAAA,EACnB,QAAA;AAAA,EACA,GAAA,GAAM,KAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,UAAA,GAAa,KAAA;AAAA,EACb,YAAA,GAAe,EAAA;AAAA,EACf,SAAA,GAAY;AACd,CAAA,EAAc;AACZ,EAAA,MAAM,QAAA,GACJ,GAAA,KAAQ,IAAA,GACJ,qBAAA,GACA,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACpC,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA,IAAO,MAAA;AACf,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,QAAA,GAAW,CAAA,gBAAA,EAAmB,QAAQ,CAAA,CAAA,GAAK,EAAA;AAAA,IAC3C,SAAA,GAAY,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,GAAK;AAAA,GAChD,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,SAAA,EAAY,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACpC,gBAAA,EAAe,MAAA;AAAA,MACf,UAAA,EAAU,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAC,CAAA;AAAA,MAC7B,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,iBAAA,EAAiB,OAAO,UAAU,CAAA;AAAA,MAClC,iBAAe,YAAA,IAAgB,MAAA;AAAA,MAC/B,OAAO,KAAA,IAAS,MAAA;AAAA,MAEf;AAAA;AAAA,GACH;AAEJ","file":"chunk-RL6COPKF.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport type { DividerSides } from './divider-sides.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface ListProps {\n  children?: KerfUiContent;\n  /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */\n  gap?: boolean | UiSpaceName | CssLength;\n  /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  /** Own vertical scrolling and overscroll containment. */\n  scrollable?: boolean;\n  /** Physical divider edges in canonical top/right/bottom/left order. */\n  dividerSides?: DividerSides;\n  className?: string;\n}\n\n/** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */\nexport function List({\n  children,\n  gap = false,\n  flex = false,\n  scrollable = false,\n  dividerSides = '',\n  className = '',\n}: ListProps) {\n  const gapValue =\n    gap === true\n      ? 'var(--kui-list-gap)'\n      : spaceNames.includes(gap as UiSpaceName)\n        ? space(gap as UiSpaceName)\n        : gap || undefined;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    gapValue ? `--_kui-list-gap:${gapValue}` : '',\n    flexValue ? `--_kui-list-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-list ${className}`.trim()}\n      data-component=\"list\"\n      data-gap={String(Boolean(gap))}\n      data-flex={String(Boolean(flex))}\n      data-scrollable={String(scrollable)}\n      divider-sides={dividerSides || undefined}\n      style={style || undefined}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\nexport type { DividerSides } from './divider-sides.js';\n"]}