@adia-ai/web-components 0.6.36 → 0.6.37

package/components/toc/toc.yaml

@@ -0,0 +1,180 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITableOfContents
+tag: toc-ui
+status: stable
+component: TableOfContents
+category: navigation
+version: 1
+description: |
+  Auto-generated in-page table of contents. Scans a target container
+  for headings (default `h2,h3`), ensures each has an `id` (slugifies
+  the text content if missing), and stamps a `<nav>` list of anchor
+  links. An `IntersectionObserver` tracks the active heading and
+  applies `[data-active]` to the matching link so consumers can style
+  the currently-visible section. Smooth-scroll on click is handled by
+  the global `scroll-behavior: smooth` set in resets.css.
+
+  Pair with a sticky container (`position: sticky; top: <offset>;`) in
+  an aside / right rail for the classic docs-site outline pattern.
+props:
+  target:
+    description: |
+      CSS selector pointing to the container to scan. Empty (default)
+      scans the toc-ui's parent element. Set to `#article` /
+      `[data-toc-target]` / `main` for a specific scope.
+    type: string
+    default: ""
+    reflect: true
+  headings:
+    description: |
+      CSS selector listing the heading tags to include (e.g. `h2,h3`).
+      The selector is matched against the target container's
+      descendants. Default `h2,h3` produces the common two-level
+      outline.
+    type: string
+    default: "h2,h3"
+    reflect: true
+  offset:
+    description: |
+      Top offset in pixels for active-state detection. The
+      IntersectionObserver's `rootMargin` is set to
+      `-<offset>px 0px -50% 0px` so the active item becomes the
+      heading nearest the top of the viewport BELOW any sticky header
+      chrome. Tune to match the height of your sticky topbar (default
+      `80` is a reasonable docs-shell value).
+    type: number
+    default: 80
+    reflect: true
+  label:
+    description: |
+      `aria-label` for the nav. Defaults to `Table of contents`.
+    type: string
+    default: "Table of contents"
+    reflect: true
+events:
+  section-change:
+    description: Fired when the active heading changes (the user scrolls into a new section). Detail carries the new active id.
+    detail:
+      activeId: string
+slots:
+  default:
+    description: Stamped automatically — a `<nav>` containing a flat `<ul>` of `<a href="#id">` links. Override by authoring your own content; auto-stamp is skipped when a `<nav>` is already present.
+states:
+  - name: idle
+    description: Default — no active section yet.
+  - name: active
+    description: A section is in view; the matching `<a>` carries `[data-active]`.
+    attribute: data-active
+tokens:
+  --toc-fg:
+    description: Default link color.
+    default: var(--a-fg-muted)
+  --toc-fg-active:
+    description: Active-link color.
+    default: var(--a-fg)
+  --toc-fg-hover:
+    description: Hover color.
+    default: var(--a-fg)
+  --toc-indent:
+    description: Per-depth-level indent.
+    default: var(--a-space-3)
+  --toc-gap:
+    description: Vertical gap between links.
+    default: var(--a-space-1)
+  --toc-rule-active:
+    description: Active-item indicator rule color (left border).
+    default: var(--a-accent-bg)
+  --toc-padding-block:
+    description: Per-link block padding (top/bottom).
+    default: var(--a-space-1)
+  --toc-padding-inline:
+    description: Per-link inline padding.
+    default: var(--a-space-2)
+  --toc-size:
+    description: Link font-size.
+    default: var(--a-ui-sm)
+requiredIcons: []
+a2ui:
+  rules:
+    - rule: "Use for in-page section navigation. Pair with a sticky container in an aside / right rail for the docs-site outline pattern."
+      reason: "Single-use-case primitive."
+    - rule: "Default scans the toc-ui's parent for h2/h3 headings. Set [target] to a CSS selector for a specific container; set [headings] to a comma-separated tag list (e.g. h1,h2,h3) for different depth coverage."
+      reason: "Configuration contract."
+    - rule: "Headings missing an [id] receive an auto-generated slug from their text content. Existing ids are preserved."
+      reason: "Id-assignment behavior."
+    - rule: "Smooth-scroll on click is handled by the global `scroll-behavior: smooth` in resets.css (gated by prefers-reduced-motion). Do NOT add per-toc-ui smooth-scroll JS — the global wins."
+      reason: "No duplicate scroll wiring."
+anti_patterns:
+  - wrong: |
+      <toc-ui></toc-ui>
+      <h2>...</h2><h3>...</h3>
+    why: |
+      toc-ui's default scans its PARENT for headings. If toc-ui is a
+      sibling of the content (not inside it), the scan finds the
+      headings inside the toc-ui's parent which usually means the
+      headings + the toc itself — works only by coincidence. Set
+      [target] explicitly for clarity.
+    fix: |
+      <toc-ui target="#article"></toc-ui>
+      <article id="article">
+        <h2>...</h2><h3>...</h3>
+      </article>
+examples:
+  - name: default
+    description: TOC scanning the parent container.
+    a2ui: |
+      [
+        {
+          "id": "page",
+          "component": "Section",
+          "children": ["toc", "h1", "h2-1", "p-1", "h2-2", "p-2"]
+        },
+        {"id": "toc",  "component": "TableOfContents"},
+        {"id": "h1",   "component": "Text", "variant": "title", "textContent": "Article title"},
+        {"id": "h2-1", "component": "Text", "variant": "heading", "textContent": "Introduction"},
+        {"id": "p-1",  "component": "Text", "textContent": "..."},
+        {"id": "h2-2", "component": "Text", "variant": "heading", "textContent": "Conclusion"},
+        {"id": "p-2",  "component": "Text", "textContent": "..."}
+      ]
+  - name: targeted
+    description: TOC scanning a specific article container.
+    a2ui: |
+      [
+        {
+          "id": "shell",
+          "component": "Row",
+          "children": ["toc", "article"]
+        },
+        {
+          "id": "toc",
+          "component": "TableOfContents",
+          "target": "#main-article",
+          "headings": "h2,h3,h4"
+        },
+        {
+          "id": "article",
+          "component": "Section",
+          "attrs": { "id": "main-article" },
+          "children": []
+        }
+      ]
+keywords:
+  - toc
+  - table-of-contents
+  - outline
+  - sub-nav
+  - page-nav
+  - in-page-nav
+  - heading-nav
+synonyms:
+  toc:
+    - table-of-contents
+    - outline
+  outline:
+    - toc
+    - table-of-contents
+related:
+  - aside
+  - nav
+  - link
+  - text

package/components/toolbar/toolbar.class.js

@@ -94,6 +94,9 @@ export class UIToolbar extends UIElement {
     gap:      { type: String,  default: 'sm', reflect: true },
     align:    { type: String,  default: 'start', reflect: true },
     overflow: { type: String,  default: 'menu', reflect: true },
+    // yaml documented reflect:true since v1 — closing the gap so
+    // el.bordered = true also updates [bordered] CSS state.
+    bordered: { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;

package/components/visually-hidden/visually-hidden.a2ui.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/VisuallyHidden.json",
+  "title": "VisuallyHidden",
+  "description": "Accessibility utility — content visible to screen readers but hidden\nvisually (the canonical \"sr-only\" pattern). Use for icon-only buttons,\ncontextual labels on duplicate controls, status announcements via\nlive regions, and any text the AT needs but sighted users don't.\n\nDistinct from `[hidden]` / `display:none` (hidden from EVERYONE\nincluding AT) and from `aria-label` (which replaces visible text but\ndoesn't add invisible text). When you need both visible and invisible\ntext on the same element, `<visually-hidden-ui>` is the wrapper for\nthe invisible part.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "VisuallyHidden"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<button-ui icon=\"trash\"><visually-hidden-ui>Delete</visually-hidden-ui></button-ui> OR set aria-label=\"Delete\" — but visually-hidden-ui scales to longer context (\"Delete row 42 in the orders table\") without overloading the label attribute.",
+        "why": "Icon-only buttons with no accessible name are unreadable for screen-reader users.",
+        "wrong": "<button-ui icon=\"trash\"></button-ui>"
+      }
+    ],
+    "category": "utility",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Sr-only label for an icon-only button.",
+        "a2ui": "[\n  { \"id\": \"btn\", \"component\": \"Button\", \"icon\": \"trash\", \"children\": [\"lbl\"] },\n  { \"id\": \"lbl\", \"component\": \"VisuallyHidden\", \"textContent\": \"Delete row\" }\n]\n",
+        "name": "icon-button-label"
+      }
+    ],
+    "keywords": [
+      "visually-hidden",
+      "sr-only",
+      "screen-reader",
+      "a11y",
+      "accessibility"
+    ],
+    "name": "UIVisuallyHidden",
+    "related": [
+      "text"
+    ],
+    "slots": {
+      "default": {
+        "description": "The text or content to hide visually while keeping accessible."
+      }
+    },
+    "states": [
+      {
+        "description": "Default — content is visually hidden but in the accessibility tree.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {},
+    "tag": "visually-hidden-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/visually-hidden/visually-hidden.class.js

@@ -0,0 +1,14 @@
+/**
+ * `<visually-hidden-ui>` — sr-only utility.
+ *
+ * Pure CSS atom — no template, no JS behavior. Stamps the canonical
+ * sr-only pattern (see visually-hidden.css) so consumers don't need to
+ * memorize the spell.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIVisuallyHidden extends UIElement {
+  static properties = {};
+  static template = () => null;
+}

package/components/visually-hidden/visually-hidden.css

@@ -0,0 +1,25 @@
+@scope (visually-hidden-ui) {
+  /* Canonical sr-only pattern — content available to assistive tech but
+     not painted. Avoid `display: none` (removes from a11y tree) and
+     `visibility: hidden` (removes too).
+
+     - position:absolute + clip-path:inset(100%) — hides without affecting
+       layout, with the clip-path doing the real visual removal
+     - width/height/padding/margin:0 — prevents layout impact
+     - white-space:nowrap — keeps multi-word strings on one line so the
+       clip works (a wrapping span can break the technique on some UAs)
+     - overflow:hidden + border:0 — belt-and-suspenders for cross-UA
+   */
+  :scope {
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    clip-path: inset(100%) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+  }
+}

package/components/visually-hidden/visually-hidden.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `<visually-hidden-ui>` — Accessibility utility — content visible to screen readers but hidden
+visually (the canonical "sr-only" pattern). Use for icon-only buttons,
+contextual labels on duplicate controls, status announcements via
+live regions, and any text the AT needs but sighted users don't.
+
+Distinct from `[hidden]` / `display:none` (hidden from EVERYONE
+including AT) and from `aria-label` (which replaces visible text but
+doesn't add invisible text). When you need both visible and invisible
+text on the same element, `<visually-hidden-ui>` is the wrapper for
+the invisible part.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/visually-hidden
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIVisuallyHidden extends UIElement {
+}

package/components/visually-hidden/visually-hidden.js

@@ -0,0 +1,12 @@
+/**
+ * `<visually-hidden-ui>` — auto-registers the tag on import.
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIVisuallyHidden } from './visually-hidden.class.js';
+
+defineIfFree('visually-hidden-ui', UIVisuallyHidden);
+
+export { UIVisuallyHidden };

package/components/visually-hidden/visually-hidden.yaml

@@ -0,0 +1,54 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIVisuallyHidden
+tag: visually-hidden-ui
+status: stable
+component: VisuallyHidden
+category: utility
+version: 1
+description: |
+  Accessibility utility — content visible to screen readers but hidden
+  visually (the canonical "sr-only" pattern). Use for icon-only buttons,
+  contextual labels on duplicate controls, status announcements via
+  live regions, and any text the AT needs but sighted users don't.
+
+  Distinct from `[hidden]` / `display:none` (hidden from EVERYONE
+  including AT) and from `aria-label` (which replaces visible text but
+  doesn't add invisible text). When you need both visible and invisible
+  text on the same element, `<visually-hidden-ui>` is the wrapper for
+  the invisible part.
+props: {}
+events: {}
+slots:
+  default:
+    description: The text or content to hide visually while keeping accessible.
+states:
+  - name: idle
+    description: Default — content is visually hidden but in the accessibility tree.
+traits: []
+tokens: {}
+a2ui:
+  rules:
+    - rule: 'Wrap text that screen readers need but sighted users do not — icon-only-button labels, contextual disambiguation ("Edit profile" inside a row whose visible button just says "Edit").'
+      reason: 'Accessibility — AT users need the missing context.'
+    - rule: 'Distinct from [hidden] / display:none (hides from EVERYONE) and from aria-label (replaces visible text). Use <visually-hidden-ui> when both visible AND invisible text need to coexist on the same element.'
+      reason: 'Three different hide-mechanisms with different semantics.'
+anti_patterns:
+  - wrong: '<button-ui icon="trash"></button-ui>'
+    why: 'Icon-only buttons with no accessible name are unreadable for screen-reader users.'
+    fix: '<button-ui icon="trash"><visually-hidden-ui>Delete</visually-hidden-ui></button-ui> OR set aria-label="Delete" — but visually-hidden-ui scales to longer context ("Delete row 42 in the orders table") without overloading the label attribute.'
+examples:
+  - name: icon-button-label
+    description: Sr-only label for an icon-only button.
+    a2ui: |
+      [
+        { "id": "btn", "component": "Button", "icon": "trash", "children": ["lbl"] },
+        { "id": "lbl", "component": "VisuallyHidden", "textContent": "Delete row" }
+      ]
+keywords:
+  - visually-hidden
+  - sr-only
+  - screen-reader
+  - a11y
+  - accessibility
+related:
+  - text

package/core/anchor.js

@@ -45,6 +45,9 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
     positionTryFallbacks: popover.style.positionTryFallbacks,
     margin: popover.style.margin,
     width: popover.style.width,
+    maxWidth: popover.style.maxWidth,
+    maxHeight: popover.style.maxHeight,
+    overflowY: popover.style.overflowY,
     top: popover.style.top,
     left: popover.style.left,
   };
@@ -59,9 +62,22 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
   // Let the browser flip across the opposite side + both perpendicular edges.
   popover.style.positionTryFallbacks = 'flip-block, flip-inline, flip-block flip-inline';
 
-  if (matchWidth) {
-    popover.style.width = `anchor-size(${name} width)`;
-  }
+  // Sizing concerns that follow from anchor positioning — kept here (not in
+  // popover.css) because they're the anchor module's contract:
+  //   • width: max-content — position-area defines a bounding span, NOT a
+  //     content width; without a width hint the browser stretches the popover
+  //     to fill the entire span (e.g. span-left can yield a 1300 px-wide
+  //     popover on a wide viewport). max-content sizes to content; consumer
+  //     min-width still clamps the lower bound.
+  //   • max-width / max-height — viewport safety so popovers don't escape
+  //     the visible area when the anchored content overflows.
+  //   • overflow-y: auto — required when max-height clamps (otherwise content
+  //     past the cap is silently hidden).
+  // Consumers can override per-instance via --popover-* tokens / inline style.
+  popover.style.width = matchWidth ? `anchor-size(${name} width)` : 'max-content';
+  popover.style.maxWidth = 'min(calc(100vw - 1rem), 32rem)';
+  popover.style.maxHeight = 'calc(100vh - 3rem)';
+  popover.style.overflowY = 'auto';
 
   // top/left are controlled by position-area; make sure no stale values fight it.
   popover.style.top = '';