@kerfjs/ui 5.0.0-beta.82 → 5.0.0-beta.84

package/README.md

@@ -218,6 +218,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `DialogSurface`, `PopupSurface`                                     | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`      |
 | `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`      |
 | `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`)        | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`            |
+| `openAnchoredSurface`, `openAnchoredSurfaceAt`                      | `@kerfjs/ui/anchored-surface`           | `@kerfjs/ui/anchored-surface.css`      |
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
 | `Text`, `FieldLabel`                                                | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                  |
 | `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |

package/ai/catalog-authoring.json

@@ -14,7 +14,6 @@
     "CatalogExample",
     "CatalogExampleStack",
     "wireCatalog",
-    "wireCatalogGeometryOverlay",
     "revealCatalogEntry"
   ],
   "taxonomy": {
@@ -30,7 +29,6 @@
   },
   "metadata": {
     "slot": "rootAttributes",
-    "demo": "data-demo",
-    "geometryOverlaySkip": "data-catalog-geometry-overlay-skip"
+    "demo": "data-demo"
   }
 }

package/ai/catalog-authoring.schema.json

@@ -38,11 +38,10 @@
           "CatalogExample",
           "CatalogExampleStack",
           "wireCatalog",
-          "wireCatalogGeometryOverlay",
           "revealCatalogEntry"
         ]
       },
-      "minItems": 6,
+      "minItems": 5,
       "uniqueItems": true
     },
     "taxonomy": {
@@ -94,13 +93,10 @@
     },
     "metadata": {
       "type": "object",
-      "required": ["slot", "demo", "geometryOverlaySkip"],
+      "required": ["slot", "demo"],
       "properties": {
         "slot": { "const": "rootAttributes" },
-        "demo": { "const": "data-demo" },
-        "geometryOverlaySkip": {
-          "const": "data-catalog-geometry-overlay-skip"
-        }
+        "demo": { "const": "data-demo" }
       },
       "additionalProperties": false
     }

package/ai/component-catalog.json

@@ -1059,6 +1059,7 @@
         "routing and persistence",
         "responsive replacement on larger device classes",
         "whether the bar divider follows the scroll, always shows, or never shows (chromeDividers)",
+        "whether the bar's top separator follows a sunken active surface or stays hidden (separator)",
         "optional active-scene focus (tabIndex) and persistent outline (outlined)"
       ],
       "variants": [
@@ -1067,7 +1068,8 @@
         "badged tabs (count or text-free dot)",
         "one NavStack per tab",
         "bar divider only while the active scene continues below it (wired by wireScrollDividers)",
-        "permanent or no bar divider (chromeDividers always or none)"
+        "permanent or no bar divider (chromeDividers always or none)",
+        "sunken active-scene separator (separator auto or hidden)"
       ],
       "accessibility": [
         "Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.",
@@ -1081,7 +1083,7 @@
         "padding": "self",
         "notes": [
           "The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
-          "The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border."
+          "The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it."
         ]
       },
       "delivery": {
@@ -2568,6 +2570,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -2744,6 +2747,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"m\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -3087,6 +3091,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={rem(0.25)}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -4657,6 +4662,72 @@
         "recipe": "docs/component-selection.md#web-awesome-overlap-policy"
       }
     },
+    {
+      "id": "anchored-surface",
+      "name": "AnchoredSurface",
+      "category": "Feedback",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A styled non-modal surface for app-owned interactive help or popup content, anchored to an element or pointer.",
+      "uses": [],
+      "purpose": "Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.",
+      "publicExports": [
+        "openAnchoredSurface",
+        "openAnchoredSurfaceAt"
+      ],
+      "useWhen": [
+        "Show interactive help or other arbitrary content near a control or pointer, including inside a modal dialog."
+      ],
+      "avoidWhen": [
+        "Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page."
+      ],
+      "alternatives": [
+        { "id": "popup-menu", "relationship": "nearest" },
+        { "id": "wa-popup", "relationship": "prefer-over" }
+      ],
+      "appOwns": [
+        "content and action policy",
+        "opening trigger and programmatic close after an action",
+        "accessible name"
+      ],
+      "variants": [
+        "element anchor",
+        "pointer anchor",
+        "top or bottom placement",
+        "modal-dialog host"
+      ],
+      "usageExamples": [
+        {
+          "title": "Interactive help",
+          "description": "The trigger owns when to open; the returned handle closes when an action completes.",
+          "code": "const handle = openAnchoredSurface(button, () => <HelpPanel />, { label: 'Field help' });\n// Close from the app's action handler: handle.close();"
+        }
+      ],
+      "accessibility": [
+        "The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/anchored-surface",
+        "manualCssImport": "@kerfjs/ui/anchored-surface.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [
+        "--kui-anchored-surface-inset",
+        "--kui-anchored-surface-radius"
+      ],
+      "links": {
+        "catalogRoute": "?component=anchored-surface",
+        "documentation": "docs/anchored-surface.md",
+        "recipe": "docs/anchored-surface.md"
+      }
+    },
     {
       "id": "popup-menu",
       "name": "PopupMenu",

package/ai/component-composition.json

@@ -1013,6 +1013,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "whether the bar's top separator follows a sunken active surface or stays hidden (separator)",
+          "owner": "application",
+          "required": false
+        },
         {
           "id": "optional active-scene focus (tabIndex) and persistent outline (outlined)",
           "owner": "application",
@@ -1047,7 +1052,7 @@
           "padding": "self",
           "notes": [
             "The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
-            "The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border."
+            "The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it."
           ]
         }
       },
@@ -2289,6 +2294,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -2392,6 +2398,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"m\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -2591,6 +2598,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={rem(0.25)}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -3797,6 +3805,61 @@
         "composition": "README.md#web-awesome-theme"
       }
     },
+    {
+      "key": "@kerfjs/ui:anchored-surface",
+      "package": "@kerfjs/ui",
+      "id": "anchored-surface",
+      "name": "AnchoredSurface",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "content and action policy",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "opening trigger and programmatic close after an action",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "accessible name", "owner": "application", "required": false }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["feedback"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": null,
+        "publicClasses": [],
+        "publicTokens": [
+          "--kui-anchored-surface-inset",
+          "--kui-anchored-surface-radius"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:popup-menu",
       "package": "@kerfjs/ui",

package/ai/components/README.md

@@ -60,6 +60,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 
 ## Kerf UI — Feedback
 
+- [AnchoredSurface](./anchored-surface.md) — Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
 - [Feedback](./feedback.md) — Banners, empty states, and labeled progress.
 - [StateBanner](./state-banner.md) — Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
 - [EmptyState](./empty-state.md) — Actionable empty and busy content states.

package/ai/components/anchored-surface.md

@@ -0,0 +1,86 @@
+# AnchoredSurface
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:anchored-surface` · Kerf UI · component · Feedback
+
+A styled non-modal surface for app-owned interactive help or popup content, anchored to an element or pointer.
+
+## When to use
+
+Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
+
+- Show interactive help or other arbitrary content near a control or pointer, including inside a modal dialog.
+
+**Not when:**
+
+- Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page.
+
+**Alternatives:**
+
+- [PopupMenu](./popup-menu.md) (nearest)
+- [Popup](./wa-popup.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/anchored-surface` — exports `openAnchoredSurface`, `openAnchoredSurfaceAt`.
+- CSS: the browser build of `@kerfjs/ui/anchored-surface` pulls its CSS automatically; import `@kerfjs/ui/anchored-surface.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/anchored-surface`](../public-api-signatures-v1.md#kerfjsuianchored-surface) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- element anchor
+- pointer anchor
+- top or bottom placement
+- modal-dialog host
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** content and action policy; opening trigger and programmatic close after an action; accessible name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default.
+
+## Usage examples
+
+### Interactive help
+
+The trigger owns when to open; the returned handle closes when an action completes.
+
+```tsx
+const handle = openAnchoredSurface(button, () => <HelpPanel />, {
+  label: 'Field help',
+});
+// Close from the app's action handler: handle.close();
+```
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public tokens it reads: `--kui-anchored-surface-inset`, `--kui-anchored-surface-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [PopupMenu](./popup-menu.md), [Popup](./wa-popup.md).
+- Docs: [`docs/anchored-surface.md`](../../docs/anchored-surface.md).
+- UX catalog route: `?component=anchored-surface`.

package/ai/components/tab-navigator.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 - one NavStack per tab
 - bar divider only while the active scene continues below it (wired by wireScrollDividers)
 - permanent or no bar divider (chromeDividers always or none)
+- sunken active-scene separator (separator auto or hidden)
 
 ## Composition
 
@@ -53,7 +54,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 
 ## State and wiring
 
-**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); optional active-scene focus (tabIndex) and persistent outline (outlined).
+**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); whether the bar's top separator follows a sunken active surface or stays hidden (separator); optional active-scene focus (tabIndex) and persistent outline (outlined).
 
 **Wiring:** `wireTabNavigator`, `wireScrollDividers` is required.
 
@@ -69,7 +70,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 Margin: none · border: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
 - The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
-- The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border.
+- The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it.
 
 ## Accessibility