@cordwainer/cw-elements 1.2.3 → 1.3.0-alpha.1

package/dist/custom-elements.json

@@ -6309,6 +6309,14 @@
               "static": true,
               "default": "{ 'cw-checkbox': CwCheckbox, 'cw-icon': CwIcon, 'cw-spinner': CwSpinner }"
             },
+            {
+              "kind": "field",
+              "name": "#stopThemeFallback",
+              "privacy": "private",
+              "type": {
+                "text": "() => void | undefined"
+              }
+            },
             {
               "kind": "field",
               "name": "columns",
@@ -11760,6 +11768,198 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/logo/logo.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "CwLogo",
+          "cssProperties": [
+            {
+              "description": "The height of the logo. Width scales automatically.",
+              "name": "--cw-logo-height"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The component's base wrapper (an `<a>` when `href` is set, otherwise a `<span>`).",
+              "name": "base"
+            },
+            {
+              "description": "The light-mode (default) logo image.",
+              "name": "image"
+            },
+            {
+              "description": "The dark-mode logo image.",
+              "name": "image-dark"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Custom logo markup (e.g. an inline `<svg>` or `<picture>`), overriding `image`/`dark-image`.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "localize",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new LocalizeController(this)"
+            },
+            {
+              "kind": "field",
+              "name": "image",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The default (light-mode) logo image URL.",
+              "attribute": "image"
+            },
+            {
+              "kind": "field",
+              "name": "darkImage",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The dark-mode logo image URL. Falls back to `image` when unset.",
+              "attribute": "dark-image"
+            },
+            {
+              "kind": "field",
+              "name": "href",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "When set, the logo renders as a link to this URL — typically the site's home page.",
+              "attribute": "href"
+            },
+            {
+              "kind": "field",
+              "name": "target",
+              "type": {
+                "text": "'_blank' | '_parent' | '_self' | '_top' | ''"
+              },
+              "default": "''",
+              "description": "Tells the browser where to open the link. Only used when `href` is present.",
+              "attribute": "target"
+            },
+            {
+              "kind": "field",
+              "name": "rel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'noreferrer noopener'",
+              "description": "The `rel` attribute for the link. Only used when `href` is present. Mirrors `<cw-button>`'s\ndefault of `noreferrer noopener` as a safe default when `target` is used.",
+              "attribute": "rel"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The accessible name for the logo. Defaults to a localized \"Home\" — for the best experience,\npass a brand-specific value instead, e.g. `label=\"Acme home\"`.",
+              "attribute": "label"
+            },
+            {
+              "kind": "field",
+              "name": "#stopThemeFallback",
+              "privacy": "private",
+              "type": {
+                "text": "() => void | undefined"
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "image",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The default (light-mode) logo image URL.",
+              "fieldName": "image"
+            },
+            {
+              "name": "dark-image",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The dark-mode logo image URL. Falls back to `image` when unset.",
+              "fieldName": "darkImage"
+            },
+            {
+              "name": "href",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "When set, the logo renders as a link to this URL — typically the site's home page.",
+              "fieldName": "href"
+            },
+            {
+              "name": "target",
+              "type": {
+                "text": "'_blank' | '_parent' | '_self' | '_top' | ''"
+              },
+              "default": "''",
+              "description": "Tells the browser where to open the link. Only used when `href` is present.",
+              "fieldName": "target"
+            },
+            {
+              "name": "rel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'noreferrer noopener'",
+              "description": "The `rel` attribute for the link. Only used when `href` is present. Mirrors `<cw-button>`'s\ndefault of `noreferrer noopener` as a safe default when `target` is used.",
+              "fieldName": "rel"
+            },
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The accessible name for the logo. Defaults to a localized \"Home\" — for the best experience,\npass a brand-specific value instead, e.g. `label=\"Acme home\"`.",
+              "fieldName": "label"
+            }
+          ],
+          "superclass": {
+            "name": "CwElement",
+            "module": "/src/internal/cw-element.js"
+          },
+          "summary": "A branding mark for a site's navigation, header, or footer, with automatic light/dark\nimage swapping and an optional home link.",
+          "tagNameWithoutPrefix": "logo",
+          "tagName": "cw-logo",
+          "customElement": true,
+          "jsDoc": "/**\n * @summary A branding mark for a site's navigation, header, or footer, with automatic light/dark\n * image swapping and an optional home link.\n * @documentation https://cordwainer.dev/components/logo\n * @status experimental\n * @since 1.3\n *\n * @slot - Custom logo markup (e.g. an inline `<svg>` or `<picture>`), overriding `image`/`dark-image`.\n *\n * @csspart base - The component's base wrapper (an `<a>` when `href` is set, otherwise a `<span>`).\n * @csspart image - The light-mode (default) logo image.\n * @csspart image-dark - The dark-mode logo image.\n *\n * @cssproperty --cw-logo-height - The height of the logo. Width scales automatically.\n */",
+          "documentation": "https://cordwainer.dev/components/logo",
+          "status": "experimental",
+          "since": "1.3"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "CwLogo",
+            "module": "components/logo/logo.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/menu/menu.js",
@@ -13457,6 +13657,542 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/primary-navigation/primary-navigation.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "CwPrimaryNavigation",
+          "cssParts": [
+            {
+              "description": "The component's base wrapper, a `<nav>` landmark element.",
+              "name": "base"
+            },
+            {
+              "description": "The hamburger toggle button, shown below `mobile-breakpoint`.",
+              "name": "toggle"
+            },
+            {
+              "description": "The container that wraps the slotted navigation items.",
+              "name": "menu"
+            }
+          ],
+          "slots": [
+            {
+              "description": "One or more `<cw-primary-navigation-item>` elements.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "dependencies",
+              "type": {
+                "text": "object"
+              },
+              "static": true,
+              "default": "{ 'cw-icon': CwIcon }"
+            },
+            {
+              "kind": "field",
+              "name": "localize",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new LocalizeController(this)"
+            },
+            {
+              "kind": "field",
+              "name": "resizeObserver",
+              "type": {
+                "text": "ResizeObserver"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "menu",
+              "type": {
+                "text": "HTMLElement"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "defaultSlot",
+              "type": {
+                "text": "HTMLSlotElement"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isMobile",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Indicates whether or not the mobile navigation panel is open. Only meaningful below `mobile-breakpoint` — use\n`show()`/`hide()` to animate it, or toggle this attribute directly.",
+              "attribute": "open",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The accessible label for the `<nav>` landmark. Defaults to a localized \"Main navigation\".",
+              "attribute": "label"
+            },
+            {
+              "kind": "field",
+              "name": "mobileBreakpoint",
+              "type": {
+                "text": "number"
+              },
+              "default": "768",
+              "description": "The viewport width, in pixels, below which the hamburger toggle and collapsible panel engage.",
+              "attribute": "mobile-breakpoint"
+            },
+            {
+              "kind": "method",
+              "name": "updateMobileState",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "handleResize",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "entries",
+                  "type": {
+                    "text": "ResizeObserverEntry[]"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handleToggleClick",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "getAllItems",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "handleItemShow",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handleMobileChange"
+            },
+            {
+              "kind": "method",
+              "name": "handleOpenChange"
+            },
+            {
+              "kind": "method",
+              "name": "show",
+              "description": "Opens the mobile navigation panel. No-op above `mobile-breakpoint`."
+            },
+            {
+              "kind": "method",
+              "name": "hide",
+              "description": "Closes the mobile navigation panel. No-op above `mobile-breakpoint`."
+            }
+          ],
+          "events": [
+            {
+              "description": "Emitted when the mobile navigation panel opens.",
+              "name": "cw-show",
+              "reactName": "onCwShow",
+              "eventName": "CwShowEvent"
+            },
+            {
+              "description": "Emitted after the mobile navigation panel opens and all animations are complete.",
+              "name": "cw-after-show",
+              "reactName": "onCwAfterShow",
+              "eventName": "CwAfterShowEvent"
+            },
+            {
+              "description": "Emitted when the mobile navigation panel closes.",
+              "name": "cw-hide",
+              "reactName": "onCwHide",
+              "eventName": "CwHideEvent"
+            },
+            {
+              "description": "Emitted after the mobile navigation panel closes and all animations are complete.",
+              "name": "cw-after-hide",
+              "reactName": "onCwAfterHide",
+              "eventName": "CwAfterHideEvent"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Indicates whether or not the mobile navigation panel is open. Only meaningful below `mobile-breakpoint` — use\n`show()`/`hide()` to animate it, or toggle this attribute directly.",
+              "fieldName": "open"
+            },
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The accessible label for the `<nav>` landmark. Defaults to a localized \"Main navigation\".",
+              "fieldName": "label"
+            },
+            {
+              "name": "mobile-breakpoint",
+              "type": {
+                "text": "number"
+              },
+              "default": "768",
+              "description": "The viewport width, in pixels, below which the hamburger toggle and collapsible panel engage.",
+              "fieldName": "mobileBreakpoint"
+            }
+          ],
+          "superclass": {
+            "name": "CwElement",
+            "module": "/src/internal/cw-element.js"
+          },
+          "summary": "Top-level site navigation with a responsive hamburger disclosure for narrow viewports.",
+          "tagNameWithoutPrefix": "primary-navigation",
+          "tagName": "cw-primary-navigation",
+          "customElement": true,
+          "jsDoc": "/**\n * @summary Top-level site navigation with a responsive hamburger disclosure for narrow viewports.\n * @documentation https://cordwainer.dev/components/primary-navigation\n * @status experimental\n * @since 1.3\n *\n * @dependency cw-icon\n *\n * @slot - One or more `<cw-primary-navigation-item>` elements.\n *\n * @event cw-show - Emitted when the mobile navigation panel opens.\n * @event cw-after-show - Emitted after the mobile navigation panel opens and all animations are complete.\n * @event cw-hide - Emitted when the mobile navigation panel closes.\n * @event cw-after-hide - Emitted after the mobile navigation panel closes and all animations are complete.\n *\n * @csspart base - The component's base wrapper, a `<nav>` landmark element.\n * @csspart toggle - The hamburger toggle button, shown below `mobile-breakpoint`.\n * @csspart menu - The container that wraps the slotted navigation items.\n *\n * @animation primary-navigation.show - The animation to use when the mobile navigation panel opens.\n * @animation primary-navigation.hide - The animation to use when the mobile navigation panel closes.\n */",
+          "documentation": "https://cordwainer.dev/components/primary-navigation",
+          "status": "experimental",
+          "since": "1.3",
+          "dependencies": [
+            "cw-icon"
+          ],
+          "animations": [
+            {
+              "name": "primary-navigation.show",
+              "description": "The animation to use when the mobile navigation panel opens."
+            },
+            {
+              "name": "primary-navigation.hide",
+              "description": "The animation to use when the mobile navigation panel closes."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "CwPrimaryNavigation",
+            "module": "components/primary-navigation/primary-navigation.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "components/primary-navigation-item/primary-navigation-item.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "CwPrimaryNavigationItem",
+          "cssParts": [
+            {
+              "description": "The component's base wrapper.",
+              "name": "base"
+            },
+            {
+              "description": "The internal `<a>`, present only when `href` is set.",
+              "name": "link"
+            },
+            {
+              "description": "The internal `<cw-dropdown>`, present only when a dropdown menu is slotted in.",
+              "name": "trigger"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The item's label content (text, or an icon + text).",
+              "name": ""
+            },
+            {
+              "description": "A `<cw-primary-navigation-menu>` with this item's dropdown links. Its presence switches the item from a link to a disclosure trigger. Ignored when `href` is also set.",
+              "name": "menu"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "dependencies",
+              "type": {
+                "text": "object"
+              },
+              "static": true,
+              "default": "{ 'cw-dropdown': CwDropdown, 'cw-icon': CwIcon }"
+            },
+            {
+              "kind": "field",
+              "name": "dropdown",
+              "type": {
+                "text": "CwDropdown | undefined"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "menuSlot",
+              "type": {
+                "text": "HTMLSlotElement | undefined"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "hasMenu",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the item's dropdown is currently open. Always `false` for link/plain items."
+            },
+            {
+              "kind": "field",
+              "name": "href",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The URL to navigate to. When set, the item renders as a link. Mutually exclusive with a slotted dropdown menu.",
+              "attribute": "href"
+            },
+            {
+              "kind": "field",
+              "name": "target",
+              "type": {
+                "text": "'_blank' | '_parent' | '_self' | '_top' | undefined"
+              },
+              "description": "Tells the browser where to open the link. Only used when `href` is set.",
+              "attribute": "target"
+            },
+            {
+              "kind": "field",
+              "name": "rel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'noreferrer noopener'",
+              "description": "The `rel` attribute for the link. Only used when `href` is set.",
+              "attribute": "rel"
+            },
+            {
+              "kind": "field",
+              "name": "current",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Indicates this item represents the current page. Reflects `aria-current=\"page\"` on the internal link. The\ncomponent has no router/URL awareness — consumers set this explicitly based on their own routing state.",
+              "attribute": "current",
+              "reflects": true
+            },
+            {
+              "kind": "method",
+              "name": "handleMenuSlotChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "handleDropdownShow",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "handleDropdownHide",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "show",
+              "description": "Opens the item's dropdown, if it has one. No-op for link/plain items."
+            },
+            {
+              "kind": "method",
+              "name": "hide",
+              "description": "Closes the item's dropdown, if it has one. No-op for link/plain items."
+            }
+          ],
+          "events": [
+            {
+              "description": "Emitted when the item's dropdown opens.",
+              "name": "cw-show",
+              "reactName": "onCwShow",
+              "eventName": "CwShowEvent"
+            },
+            {
+              "description": "Emitted after the item's dropdown opens and all animations are complete.",
+              "name": "cw-after-show",
+              "reactName": "onCwAfterShow",
+              "eventName": "CwAfterShowEvent"
+            },
+            {
+              "description": "Emitted when the item's dropdown closes.",
+              "name": "cw-hide",
+              "reactName": "onCwHide",
+              "eventName": "CwHideEvent"
+            },
+            {
+              "description": "Emitted after the item's dropdown closes and all animations are complete.",
+              "name": "cw-after-hide",
+              "reactName": "onCwAfterHide",
+              "eventName": "CwAfterHideEvent"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "href",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The URL to navigate to. When set, the item renders as a link. Mutually exclusive with a slotted dropdown menu.",
+              "fieldName": "href"
+            },
+            {
+              "name": "target",
+              "type": {
+                "text": "'_blank' | '_parent' | '_self' | '_top' | undefined"
+              },
+              "description": "Tells the browser where to open the link. Only used when `href` is set.",
+              "fieldName": "target"
+            },
+            {
+              "name": "rel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'noreferrer noopener'",
+              "description": "The `rel` attribute for the link. Only used when `href` is set.",
+              "fieldName": "rel"
+            },
+            {
+              "name": "current",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Indicates this item represents the current page. Reflects `aria-current=\"page\"` on the internal link. The\ncomponent has no router/URL awareness — consumers set this explicitly based on their own routing state.",
+              "fieldName": "current"
+            }
+          ],
+          "superclass": {
+            "name": "CwElement",
+            "module": "/src/internal/cw-element.js"
+          },
+          "summary": "A top-level entry in a `<cw-primary-navigation>`, rendered as a link or, when it has a\n`<cw-primary-navigation-menu>` slotted in, a disclosure trigger for a dropdown of sub-links.",
+          "tagNameWithoutPrefix": "primary-navigation-item",
+          "tagName": "cw-primary-navigation-item",
+          "customElement": true,
+          "jsDoc": "/**\n * @summary A top-level entry in a `<cw-primary-navigation>`, rendered as a link or, when it has a\n * `<cw-primary-navigation-menu>` slotted in, a disclosure trigger for a dropdown of sub-links.\n * @documentation https://cordwainer.dev/components/primary-navigation-item\n * @status experimental\n * @since 1.3\n *\n * @dependency cw-dropdown\n * @dependency cw-icon\n *\n * @slot - The item's label content (text, or an icon + text).\n * @slot menu - A `<cw-primary-navigation-menu>` with this item's dropdown links. Its presence switches the item\n * from a link to a disclosure trigger. Ignored when `href` is also set.\n *\n * @event cw-show - Emitted when the item's dropdown opens.\n * @event cw-after-show - Emitted after the item's dropdown opens and all animations are complete.\n * @event cw-hide - Emitted when the item's dropdown closes.\n * @event cw-after-hide - Emitted after the item's dropdown closes and all animations are complete.\n *\n * @csspart base - The component's base wrapper.\n * @csspart link - The internal `<a>`, present only when `href` is set.\n * @csspart trigger - The internal `<cw-dropdown>`, present only when a dropdown menu is slotted in.\n */",
+          "documentation": "https://cordwainer.dev/components/primary-navigation-item",
+          "status": "experimental",
+          "since": "1.3",
+          "dependencies": [
+            "cw-dropdown",
+            "cw-icon"
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "CwPrimaryNavigationItem",
+            "module": "components/primary-navigation-item/primary-navigation-item.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "components/primary-navigation-menu/primary-navigation-menu.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "CwPrimaryNavigationMenu",
+          "cssParts": [
+            {
+              "description": "The component's base wrapper.",
+              "name": "base"
+            }
+          ],
+          "slots": [
+            {
+              "description": "One or more plain `<a>` elements.",
+              "name": ""
+            }
+          ],
+          "members": [],
+          "superclass": {
+            "name": "CwElement",
+            "module": "/src/internal/cw-element.js"
+          },
+          "summary": "A simple flat list of links shown in a `<cw-primary-navigation-item>`'s dropdown. Deliberately\nminimal — no headings, grouping, multi-column layout, or promo slot; styles plain `<a>` elements only.",
+          "tagNameWithoutPrefix": "primary-navigation-menu",
+          "tagName": "cw-primary-navigation-menu",
+          "customElement": true,
+          "jsDoc": "/**\n * @summary A simple flat list of links shown in a `<cw-primary-navigation-item>`'s dropdown. Deliberately\n * minimal — no headings, grouping, multi-column layout, or promo slot; styles plain `<a>` elements only.\n * @documentation https://cordwainer.dev/components/primary-navigation-menu\n * @status experimental\n * @since 1.3\n *\n * @slot - One or more plain `<a>` elements.\n *\n * @csspart base - The component's base wrapper.\n */",
+          "documentation": "https://cordwainer.dev/components/primary-navigation-menu",
+          "status": "experimental",
+          "since": "1.3"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "CwPrimaryNavigationMenu",
+            "module": "components/primary-navigation-menu/primary-navigation-menu.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/progress-bar/progress-bar.js",
@@ -22023,7 +22759,7 @@
   "package": {
     "name": "@cordwainer/cw-elements",
     "description": "Cordwainer Elements — Web Component Library, a hard fork of Shoelace (@shoelace-style/shoelace).",
-    "version": "1.2.3",
+    "version": "1.3.0-alpha.1",
     "author": "Matt Hand",
     "homepage": "https://cordwainer.dev",
     "license": "MIT"