@adia-ai/web-components 0.4.6 → 0.4.8

package/components/kbd/kbd.yaml

@@ -1,5 +1,3 @@
-# Generated by scripts/migrate-yamls-to-v1.mjs — migrated to v1 contract.
-# Edit this file; run `npm run build:components` to regenerate a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIKbd
 tag: kbd-ui
@@ -11,207 +9,78 @@ props:
   size:
     description: Sizing scale (compact tier — sm / md only).
     type: string
-    default: ""
+    default: ''
     enum:
-      - sm
-      - md
+    - sm
+    - md
     reflect: true
 events: {}
 slots:
   default:
     description: Key label text
 states:
-  - name: idle
-    description: Default, ready for interaction.
+- name: idle
+  description: Default, ready for interaction.
 traits: []
 tokens: {}
 a2ui:
   rules: []
 anti_patterns: []
 examples:
-  - name: kbd-shortcuts
-    description: Card displaying a grid of keyboard shortcut rows with key badges and descriptions.
-    a2ui: >-
-      [
-        {
-          "id": "root",
-          "component": "Card",
-          "children": [
-            "hdr",
-            "sec"
-          ]
-        },
-        {
-          "id": "hdr",
-          "component": "Header",
-          "children": [
-            "title"
-          ]
-        },
-        {
-          "id": "title",
-          "component": "Text",
-          "slot": "heading",
-          "textContent": "Keyboard Shortcuts"
-        },
-        {
-          "id": "sec",
-          "component": "Section",
-          "children": [
-            "grid"
-          ]
-        },
-        {
-          "id": "grid",
-          "component": "Grid",
-          "columns": 1,
-          "gap": "2",
-          "children": [
-            "r1",
-            "r2",
-            "r3",
-            "r4",
-            "r5",
-            "r6"
-          ]
-        },
-        {
-          "id": "r1",
-          "component": "Row",
-          "children": [
-            "k1",
-            "d1"
-          ]
-        },
-        {
-          "id": "k1",
-          "component": "Kbd",
-          "text": "Ctrl+K"
-        },
-        {
-          "id": "d1",
-          "component": "Text",
-          "textContent": "Open command palette"
-        },
-        {
-          "id": "r2",
-          "component": "Row",
-          "children": [
-            "k2",
-            "d2"
-          ]
-        },
-        {
-          "id": "k2",
-          "component": "Kbd",
-          "text": "Ctrl+S"
-        },
-        {
-          "id": "d2",
-          "component": "Text",
-          "textContent": "Save current file"
-        },
-        {
-          "id": "r3",
-          "component": "Row",
-          "children": [
-            "k3",
-            "d3"
-          ]
-        },
-        {
-          "id": "k3",
-          "component": "Kbd",
-          "text": "Ctrl+Z"
-        },
-        {
-          "id": "d3",
-          "component": "Text",
-          "textContent": "Undo last action"
-        },
-        {
-          "id": "r4",
-          "component": "Row",
-          "children": [
-            "k4",
-            "d4"
-          ]
-        },
-        {
-          "id": "k4",
-          "component": "Kbd",
-          "text": "Ctrl+Shift+P"
-        },
-        {
-          "id": "d4",
-          "component": "Text",
-          "textContent": "Toggle preview"
-        },
-        {
-          "id": "r5",
-          "component": "Row",
-          "children": [
-            "k5",
-            "d5"
-          ]
-        },
-        {
-          "id": "k5",
-          "component": "Kbd",
-          "text": "Ctrl+N"
-        },
-        {
-          "id": "d5",
-          "component": "Text",
-          "textContent": "Create new document"
-        },
-        {
-          "id": "r6",
-          "component": "Row",
-          "children": [
-            "k6",
-            "d6"
-          ]
-        },
-        {
-          "id": "k6",
-          "component": "Kbd",
-          "text": "Esc"
-        },
-        {
-          "id": "d6",
-          "component": "Text",
-          "textContent": "Close dialog"
-        }
-      ]
+- name: kbd-shortcuts
+  description: Card displaying a grid of keyboard shortcut rows with key badges and descriptions.
+  a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\"\n\
+    \    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\"\n    ]\n\
+    \  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"\
+    Keyboard Shortcuts\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"\
+    grid\"\n    ]\n  },\n  {\n    \"id\": \"grid\",\n    \"component\": \"Grid\",\n    \"columns\": 1,\n    \"gap\": \"2\"\
+    ,\n    \"children\": [\n      \"r1\",\n      \"r2\",\n      \"r3\",\n      \"r4\",\n      \"r5\",\n      \"r6\"\n    ]\n\
+    \  },\n  {\n    \"id\": \"r1\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k1\",\n      \"d1\"\n    ]\n\
+    \  },\n  {\n    \"id\": \"k1\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+K\"\n  },\n  {\n    \"id\": \"d1\"\
+    ,\n    \"component\": \"Text\",\n    \"textContent\": \"Open command palette\"\n  },\n  {\n    \"id\": \"r2\",\n    \"\
+    component\": \"Row\",\n    \"children\": [\n      \"k2\",\n      \"d2\"\n    ]\n  },\n  {\n    \"id\": \"k2\",\n    \"\
+    component\": \"Kbd\",\n    \"text\": \"Ctrl+S\"\n  },\n  {\n    \"id\": \"d2\",\n    \"component\": \"Text\",\n    \"\
+    textContent\": \"Save current file\"\n  },\n  {\n    \"id\": \"r3\",\n    \"component\": \"Row\",\n    \"children\": [\n\
+    \      \"k3\",\n      \"d3\"\n    ]\n  },\n  {\n    \"id\": \"k3\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+Z\"\
+    \n  },\n  {\n    \"id\": \"d3\",\n    \"component\": \"Text\",\n    \"textContent\": \"Undo last action\"\n  },\n  {\n\
+    \    \"id\": \"r4\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k4\",\n      \"d4\"\n    ]\n  },\n  {\n\
+    \    \"id\": \"k4\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+Shift+P\"\n  },\n  {\n    \"id\": \"d4\",\n  \
+    \  \"component\": \"Text\",\n    \"textContent\": \"Toggle preview\"\n  },\n  {\n    \"id\": \"r5\",\n    \"component\"\
+    : \"Row\",\n    \"children\": [\n      \"k5\",\n      \"d5\"\n    ]\n  },\n  {\n    \"id\": \"k5\",\n    \"component\"\
+    : \"Kbd\",\n    \"text\": \"Ctrl+N\"\n  },\n  {\n    \"id\": \"d5\",\n    \"component\": \"Text\",\n    \"textContent\"\
+    : \"Create new document\"\n  },\n  {\n    \"id\": \"r6\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"\
+    k6\",\n      \"d6\"\n    ]\n  },\n  {\n    \"id\": \"k6\",\n    \"component\": \"Kbd\",\n    \"text\": \"Esc\"\n  },\n\
+    \  {\n    \"id\": \"d6\",\n    \"component\": \"Text\",\n    \"textContent\": \"Close dialog\"\n  }\n]"
 keywords:
-  - kbd
-  - command
-  - shortcut
-  - hotkey
-  - keyboard
-  - keybinding
+- kbd
+- command
+- shortcut
+- hotkey
+- keyboard
+- keybinding
 synonyms:
   command:
-    - command
-    - palette
-    - kbd
-    - shortcut
+  - command
+  - palette
+  - kbd
+  - shortcut
   hotkey:
-    - kbd
-    - shortcut
-    - command
+  - kbd
+  - shortcut
+  - command
   keybinding:
-    - kbd
-    - shortcut
-    - command
+  - kbd
+  - shortcut
+  - command
   keyboard:
-    - kbd
-    - shortcut
-    - command
+  - kbd
+  - shortcut
+  - command
   shortcut:
-    - kbd
-    - shortcut
-    - command
+  - kbd
+  - shortcut
+  - command
+  tags:
+  - Keyboard
 related:
-  - grid
+- grid

package/components/link/class.js

@@ -0,0 +1,187 @@
+/**
+ * Non-side-effect class export for `<link-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/link`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <link-ui> — Inline navigation primitive.
+ *
+ *   <link-ui text="Terms of Service" href="/terms"></link-ui>
+ *   <link-ui href="https://example.com" target="_blank">Read more</link-ui>
+ *   <link-ui text="Sign in" variant="quiet" href="/signin"></link-ui>
+ *
+ * Semantic <a href> wrapper for cross-page navigation. Sibling of
+ * <button-ui> — the two are NOT interchangeable:
+ *   - <button-ui>: triggers an action (submit, open modal, copy, run handler)
+ *   - <link-ui>:   navigates to a URL (real <a href> under the hood)
+ *
+ * The previous design conflated these via `<button-ui variant="link">`,
+ * which produced a button DOM with link-look styling — accessibility
+ * trees announced "button" for things screen-reader users expected to
+ * be links, middle-click did nothing instead of opening new tabs,
+ * search engines didn't see the link targets.
+ *
+ * Implementation: stamps an internal <a> element on connected() unless
+ * a child <a> is already present (slot-passthrough mode for advanced
+ * authoring). Renders the `text` prop into a <span> inside the <a>.
+ * For target="_blank", auto-adds rel="noopener noreferrer" unless an
+ * explicit rel is set.
+ *
+ * Properties:
+ *   text     — visible label
+ *   href     — destination URL (required for native nav semantics)
+ *   target   — _self | _blank | _parent | _top
+ *   rel      — explicit rel (defaults to noopener noreferrer for _blank)
+ *   variant  — default | subtle | quiet
+ *   block    — full-width row
+ *   disabled — suppress activation
+ *   icon     — optional leading Phosphor icon
+ *
+ * Events:
+ *   press — bubbles on click/Enter with detail { href, target }. Fires
+ *           BEFORE native navigation. preventDefault() the underlying
+ *           click event to suppress native nav and route through the
+ *           A2UI action-handler system.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UILink extends UIElement {
+  static properties = {
+    text:     { type: String,  default: '', reflect: true },
+    href:     { type: String,  default: '', reflect: true },
+    target:   { type: String,  default: '', reflect: true },
+    rel:      { type: String,  default: '', reflect: true },
+    variant:  { type: String,  default: 'default', reflect: true },
+    block:    { type: Boolean, default: false, reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+    icon:     { type: String,  default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #onClick = (e) => {
+    if (this.disabled) {
+      e.preventDefault();
+      return;
+    }
+    // Dispatch press BEFORE native navigation so handlers can intercept.
+    const detail = { href: this.href, target: this.target };
+    const press = new CustomEvent('press', {
+      bubbles: true,
+      cancelable: true,
+      detail,
+    });
+    const allowed = this.dispatchEvent(press);
+    // If a handler called preventDefault on the press event, suppress
+    // the underlying anchor's native navigation too.
+    if (!allowed) e.preventDefault();
+  };
+
+  #onKey = (e) => {
+    // Links are activated by Enter only (NOT Space — that's button
+    // semantics). The native <a> handles this already, but we wire it
+    // explicitly for the disabled-suppression case.
+    if (this.disabled && e.key === 'Enter') {
+      e.preventDefault();
+    }
+  };
+
+  #ensureAnchor() {
+    // If author provided their own <a> child, leave it alone. Otherwise
+    // stamp one with the configured href/target/rel and mark it as
+    // autostamped so render() knows it owns the anchor's attrs +
+    // content. Slot-passthrough mode (author <a> child) preserves all
+    // author-set attrs across re-renders.
+    let a = this.querySelector(':scope > a');
+    if (!a) {
+      a = document.createElement('a');
+      a.dataset.autostamped = 'true';
+      this.appendChild(a);
+    }
+    // Move any direct text/icon children into the anchor so they inherit
+    // its semantics. Skip nodes already inside the anchor.
+    const toMove = [];
+    for (const node of this.childNodes) {
+      if (node === a) continue;
+      if (node.parentNode === this) toMove.push(node);
+    }
+    for (const node of toMove) a.appendChild(node);
+    return a;
+  }
+
+  connected() {
+    const a = this.#ensureAnchor();
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('keydown', this.#onKey);
+    // Disabled handling — aria-disabled rather than removing href, so
+    // the disabled state is announced to screen readers.
+    if (this.disabled) this.setAttribute('aria-disabled', 'true');
+  }
+
+  render() {
+    const a = this.querySelector(':scope > a');
+    if (!a) return;
+
+    // Slot-passthrough detection: if the author provided their own <a>
+    // child, leave its href/target/rel alone — they intentionally
+    // configured the anchor directly. We only manage anchors we
+    // auto-stamped (marked via data-autostamped).
+    const isAutostamped = a.dataset.autostamped === 'true';
+
+    if (isAutostamped) {
+      // href: empty string = no native nav, but element is still
+      // activatable via press event (handler-driven navigation).
+      if (this.href) a.setAttribute('href', this.href);
+      else a.removeAttribute('href');
+
+      // target: passed through verbatim.
+      if (this.target) a.setAttribute('target', this.target);
+      else a.removeAttribute('target');
+
+      // rel: explicit rel wins; otherwise auto-add noopener noreferrer
+      // for _blank to prevent tab-napping / referrer leakage.
+      if (this.rel) {
+        a.setAttribute('rel', this.rel);
+      } else if (this.target === '_blank') {
+        a.setAttribute('rel', 'noopener noreferrer');
+      } else {
+        a.removeAttribute('rel');
+      }
+    }
+
+    // Disabled — keep the anchor in the tree (so SR announcement works)
+    // but communicate state via aria-disabled. Click handler short-
+    // circuits when disabled is set. This applies to both autostamped
+    // and slot-passthrough modes.
+    if (this.disabled) {
+      this.setAttribute('aria-disabled', 'true');
+      a.setAttribute('tabindex', '-1');
+    } else {
+      this.removeAttribute('aria-disabled');
+      a.removeAttribute('tabindex');
+    }
+
+    // text + icon — stamp into the anchor when the props are set and
+    // this is an autostamped anchor. Don't touch author-provided
+    // anchors' content.
+    if (isAutostamped) {
+      const iconHTML = this.icon ? `<icon-ui name="${this.icon}"></icon-ui>` : '';
+      const textHTML = this.text ? `<span>${this.text}</span>` : '';
+      a.innerHTML = `${iconHTML}${textHTML}`;
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+}

package/components/link/link.a2ui.json

@@ -80,6 +80,7 @@
       "❌ `<link-ui>` for form submission — submission is a button concern. Use `<button-ui type=\"submit\">`."
     ],
     "category": "content",
+    "composes": [],
     "events": {
       "press": {
         "description": "Bubbles when the link is activated by click or Enter. Detail: `{ href, target }`. Fires BEFORE the browser's native navigation so handlers can `preventDefault()` and route through the A2UI action handler system. If no handler intercepts, native navigation proceeds."

package/components/link/link.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `<link-ui>` — Inline navigation primitive — semantic `<a href>` wrapper. Use for
+cross-page navigation, footer / Terms-of-Service / Privacy-Policy
+inline references, "Sign in" / "Sign up" cross-page links, and any
+affordance whose purpose is to take the user somewhere (not to
+perform an action).
+
+Sibling of `<button-ui>` — they have separate semantics and must
+not be substituted for each other:
+
+| Affordance                | Use            |
+|---------------------------|----------------|
+| Submit form               | `<button-ui>`  |
+| Trigger action / modal    | `<button-ui>`  |
+| Copy to clipboard         | `<button-ui>`  |
+| Open modal / drawer       | `<button-ui>`  |
+| Navigate to another page  | `<link-ui>`    |
+| Open external URL         | `<link-ui>`    |
+| Anchor jump (#section)    | `<link-ui>`    |
+| Inline reference in prose | `<link-ui>`    |
+
+Renders `<a href="…">` internally so middle-click open-in-new-tab,
+right-click context menu, hover URL preview, search-engine
+crawlability, and bookmark-ability all work without any custom
+wiring. ARIA role is "link" (set automatically by `<a>` element).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/link
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 type LinkPressEvent = CustomEvent<unknown>;
+
+export class UILink extends UIElement {
+  /** Stretches the link to fill its container; useful for standalone link rows. */
+  block: boolean;
+  /** Suppresses navigation + applies muted styling. Sets aria-disabled. */
+  disabled: boolean;
+  /** Destination URL or anchor. Required for SEO / middle-click / hover preview semantics. If omitted, the link still dispatches the `press` event (so it can be wired through the A2UI action handler system via `handler: "navigate"`), but loses native link behaviors. */
+  href: string;
+  /** Optional leading icon (Phosphor name). Use sparingly — most inline links don't need an icon. For "open in new tab" affordance, the `target="_blank"` attribute auto-renders a trailing arrow-up-right glyph; the `icon` prop is for leading semantic icons. */
+  icon: string;
+  /** Explicit `rel` attribute. Defaults to `noopener noreferrer` when `target="_blank"` is set without an explicit rel. */
+  rel: string;
+  /** Anchor target — same semantics as HTML `<a target>`. Use `_blank` to open in new tab; the implementation automatically adds `rel="noopener noreferrer"` for `_blank` to prevent tab-napping / privacy leaks. */
+  target: '' | '_self' | '_blank' | '_parent' | '_top';
+  /** Visible link text. Falls back to default-slot content if unset. */
+  text: string;
+  /** Visual treatment. `default` underlines on rest + hover (standard link affordance). `subtle` underlines only on hover (for tighter designs where always-underlined would be noisy). `quiet` drops the link color and matches surrounding text color (used for footer-link rows where the link affordance is implied by context, not by color). */
+  variant: 'default' | 'subtle' | 'quiet';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UILink, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'press', listener: (ev: LinkPressEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}