@lostgradient/cinder 0.5.0 → 0.7.0

package/src/components/navigation-bar/index.ts

@@ -5,6 +5,7 @@ export default NavigationBar;
 export type {
   NavigationBarItemsContext,
   NavigationBarLabelVisibility,
+  NavigationBarMenuTogglePlacement,
   NavigationBarPlacement,
   NavigationBarProps,
   NavigationBarToggleAttributes,

package/src/components/navigation-bar/navigation-bar.css

@@ -133,6 +133,11 @@
       display: inline-flex;
     }
 
+    .cinder-navigation-bar[data-collapsible='true'][data-cinder-menu-toggle-placement='after-brand']
+      .cinder-navigation-bar__menu-toggle {
+      margin-inline-start: auto;
+    }
+
     .cinder-navigation-bar[data-collapsible='true'] .cinder-navigation-bar__items {
       position: absolute;
       inset-inline: 0;
@@ -173,6 +178,16 @@
       inline-size: 100%;
       justify-content: flex-start;
       padding-block: var(--cinder-space-3);
+      border-bottom: none;
+      border-inline-start: 2px solid transparent;
+      border-radius: var(--cinder-radius-sm);
+    }
+
+    .cinder-navigation-bar[data-collapsible='true']
+      .cinder-navigation-bar__items[data-open='true']
+      .cinder-navigation-item[data-variant='mobile'][data-active='true'] {
+      border-inline-start-color: var(--cinder-accent);
+      background-color: var(--cinder-surface-inset);
     }
   }
 

package/src/components/navigation-bar/navigation-bar.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic navigation bar",
       "description": "Brand, link and button navigation items, disabled state, and an action in the trailing slot.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationBar } from '@lostgradient/cinder/navigation-bar';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  let active = $state('home');\n  let mobileMenuOpen = $state(false);\n</script>\n\n<NavigationBar bind:mobileMenuOpen>\n  {#snippet brand()}\n    <strong>Acme</strong>\n  {/snippet}\n  {#snippet menuToggle(attrs)}\n    <button type=\"button\" {...attrs} aria-label={mobileMenuOpen ? 'Close menu' : 'Open menu'}>\n      <span aria-hidden=\"true\">☰</span>\n    </button>\n  {/snippet}\n  {#snippet items({ variant })}\n    <NavigationItem {variant} onclick={() => (active = 'home')} active={active === 'home'}>\n      Home\n    </NavigationItem>\n    <NavigationItem {variant} onclick={() => (active = 'docs')} active={active === 'docs'}>\n      Docs\n    </NavigationItem>\n    <NavigationItem {variant} href=\"#blog\" active={active === 'blog'}>Blog</NavigationItem>\n    <NavigationItem {variant} onclick={() => (active = 'billing')} disabled>Billing</NavigationItem>\n  {/snippet}\n  {#snippet actions()}\n    <Button variant=\"primary\" size=\"sm\" label=\"Sign up\" />\n  {/snippet}\n</NavigationBar>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationBar } from '@lostgradient/cinder/navigation-bar';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  let active = $state('home');\n  let mobileMenuOpen = $state(false);\n</script>\n\n<NavigationBar bind:mobileMenuOpen menuTogglePlacement=\"before-brand\">\n  {#snippet brand()}\n    <strong>Acme</strong>\n  {/snippet}\n  {#snippet menuToggle(attrs)}\n    <button type=\"button\" {...attrs} aria-label={mobileMenuOpen ? 'Close menu' : 'Open menu'}>\n      <span aria-hidden=\"true\">☰</span>\n    </button>\n  {/snippet}\n  {#snippet items({ variant })}\n    <NavigationItem {variant} onclick={() => (active = 'home')} active={active === 'home'}>\n      Home\n    </NavigationItem>\n    <NavigationItem {variant} onclick={() => (active = 'docs')} active={active === 'docs'}>\n      Docs\n    </NavigationItem>\n    <NavigationItem {variant} href=\"#blog\" active={active === 'blog'}>Blog</NavigationItem>\n    <NavigationItem {variant} onclick={() => (active = 'billing')} disabled>Billing</NavigationItem>\n  {/snippet}\n  {#snippet actions()}\n    <Button variant=\"primary\" size=\"sm\" label=\"Sign up\" />\n  {/snippet}\n</NavigationBar>\n"
     },
     {
       "id": "bottom-tabs",

package/src/components/navigation-bar/navigation-bar.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "class": {
+      "type": "string",
+      "description": "Custom class merged onto the root `<nav>` element."
+    },
+    "placement": {
+      "enum": ["top", "bottom"],
+      "description": "Visual placement mode. `bottom` renders a mobile tab-bar composition, but\nstill does not fix or stick itself to the viewport.",
+      "default": "top"
+    },
+    "showLabels": {
+      "enum": ["always", "active", "never"],
+      "description": "Label visibility for mobile bottom-tab compositions. Hidden labels remain in\nthe accessibility tree when wrapped in `[data-cinder-navigation-label]`.",
+      "default": "always"
+    },
+    "menuTogglePlacement": {
+      "enum": ["after-brand", "before-brand"],
+      "description": "Placement for the collapsible mobile menu toggle in top navigation bars.\nIgnored for `placement=\"bottom\"`.",
+      "default": "after-brand"
+    },
+    "mobileMenuOpen": {
+      "type": "boolean",
+      "description": "Two-way bindable open state of the mobile menu."
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "actions",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "brand",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "items",
+        "reason": "function-or-snippet",
+        "required": true,
+        "description": "Receives a context object with the current variant."
+      },
+      {
+        "name": "menuToggle",
+        "reason": "function-or-snippet",
+        "description": "Snippet receiving toggle button attributes. Consumer renders the actual <button> and should mark decorative glyphs or icons inside it as aria-hidden so the button name comes from text or aria-label, not the ornament."
+      }
+    ]
+  }
+}

package/src/components/navigation-bar/navigation-bar.schema.ts

@@ -0,0 +1,66 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    class: {
+      type: 'string',
+      description: 'Custom class merged onto the root `<nav>` element.',
+    },
+    placement: {
+      enum: ['top', 'bottom'],
+      description:
+        'Visual placement mode. `bottom` renders a mobile tab-bar composition, but\nstill does not fix or stick itself to the viewport.',
+      default: 'top',
+    },
+    showLabels: {
+      enum: ['always', 'active', 'never'],
+      description:
+        'Label visibility for mobile bottom-tab compositions. Hidden labels remain in\nthe accessibility tree when wrapped in `[data-cinder-navigation-label]`.',
+      default: 'always',
+    },
+    menuTogglePlacement: {
+      enum: ['after-brand', 'before-brand'],
+      description:
+        'Placement for the collapsible mobile menu toggle in top navigation bars.\nIgnored for `placement="bottom"`.',
+      default: 'after-brand',
+    },
+    mobileMenuOpen: {
+      type: 'boolean',
+      description: 'Two-way bindable open state of the mobile menu.',
+    },
+    label: {
+      type: 'string',
+      description:
+        "Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.",
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'actions',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'brand',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'items',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Receives a context object with the current variant.',
+      },
+      {
+        name: 'menuToggle',
+        reason: 'function-or-snippet',
+        description:
+          'Snippet receiving toggle button attributes. Consumer renders the actual <button> and should mark decorative glyphs or icons inside it as aria-hidden so the button name comes from text or aria-label, not the ornament.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/navigation-bar/navigation-bar.svelte

@@ -1,214 +1,153 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category navigation
-   * @status stable
-   * @purpose Top-level application header that pairs a brand mark with a horizontal set of navigation items and an optional mobile menu toggle.
-   * @tag navigation
-   * @tag chrome
-   * @useWhen Anchoring an app shell with primary sections, branding, and account actions across the top edge.
-   * @useWhen Providing a responsive nav that collapses items behind a menu toggle below a breakpoint.
-   * @avoidWhen Showing the ancestor trail of the current page — use breadcrumbs instead.
-   * @avoidWhen Building a tall, dense sidebar of grouped sections — use side-navigation instead.
-   * @related navigation-item, breadcrumbs, side-navigation
-   */
-  export type {
-    NavigationBarLabelVisibility,
-    NavigationBarItemsContext,
-    NavigationBarPlacement,
-    NavigationBarProps,
-    NavigationBarToggleAttributes,
-    NavigationVariant,
-  } from './navigation-bar.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import type { NavigationBarProps, NavigationVariant } from './navigation-bar.types.ts';
-  import { BROWSER as browser } from 'esm-env';
-  import { classNames } from '../../utilities/class-names.ts';
-
-  const COLLAPSIBLE_MAX_WIDTH_REM = 47.99;
-  const FALLBACK_ROOT_FONT_SIZE_PX = 16;
-  const regionId = $props.id();
-
-  let {
-    class: className,
-    placement = 'top',
-    showLabels = 'always',
-    brand,
-    items,
-    actions,
-    menuToggle,
-    mobileMenuOpen = $bindable(false),
-    label = 'Main navigation',
-    // Strip these from rest so they cannot collide with internal attributes.
-    'aria-label': _ariaLabel,
-    'data-collapsible': _dataCollapsible,
-    'data-cinder-placement': _dataCinderPlacement,
-    'data-cinder-label-visibility': _dataCinderLabelVisibility,
-    onkeydown: consumerOnKeyDown,
-    ...rest
-  }: NavigationBarProps = $props();
-  const navigationItemSelector = '[data-cinder-navigation-item]';
-
-  const isCollapsible = $derived(placement === 'top' && menuToggle !== undefined);
-  let isMobileLayout = $state(false);
-
-  const variant: NavigationVariant = $derived(
-    placement === 'bottom'
-      ? 'mobile'
-      : isCollapsible && isMobileLayout && mobileMenuOpen
+import { BROWSER as browser } from 'esm-env';
+import { classNames } from '../../utilities/class-names.ts';
+const COLLAPSIBLE_MAX_WIDTH_REM = 47.99;
+const FALLBACK_ROOT_FONT_SIZE_PX = 16;
+const regionId = $props.id();
+let { class: className, placement = 'top', showLabels = 'always', menuTogglePlacement = 'after-brand', brand, items, actions, menuToggle, mobileMenuOpen = $bindable(false), label = 'Main navigation', 
+// Strip these from rest so they cannot collide with internal attributes.
+'aria-label': _ariaLabel, 'data-collapsible': _dataCollapsible, 'data-cinder-placement': _dataCinderPlacement, 'data-cinder-label-visibility': _dataCinderLabelVisibility, 'data-cinder-menu-toggle-placement': _dataCinderMenuTogglePlacement, onkeydown: consumerOnKeyDown, ...rest } = $props();
+const navigationItemSelector = '[data-cinder-navigation-item]';
+const isCollapsible = $derived(placement === 'top' && menuToggle !== undefined);
+let isMobileLayout = $state(false);
+const variant = $derived(placement === 'bottom'
+    ? 'mobile'
+    : isCollapsible && isMobileLayout && mobileMenuOpen
         ? 'mobile'
-        : 'horizontal',
-  );
-
-  // Stores the toggle element for focus return after Escape-close.
-  let navigationBarElement: HTMLElement | null = null;
-  let toggleElement: HTMLElement | null = null;
-  let itemsRegionElement: HTMLDivElement | null = null;
-
-  function getCollapsibleMaxWidthPx(): number {
+        : 'horizontal');
+// Stores the toggle element for focus return after Escape-close.
+let navigationBarElement = null;
+let toggleElement = null;
+let itemsRegionElement = null;
+function getCollapsibleMaxWidthPx() {
     if (typeof window === 'undefined') {
-      return COLLAPSIBLE_MAX_WIDTH_REM * FALLBACK_ROOT_FONT_SIZE_PX;
+        return COLLAPSIBLE_MAX_WIDTH_REM * FALLBACK_ROOT_FONT_SIZE_PX;
     }
-
     const rootFontSize = Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
-    const baseFontSize =
-      Number.isFinite(rootFontSize) && rootFontSize > 0 ? rootFontSize : FALLBACK_ROOT_FONT_SIZE_PX;
+    const baseFontSize = Number.isFinite(rootFontSize) && rootFontSize > 0 ? rootFontSize : FALLBACK_ROOT_FONT_SIZE_PX;
     return COLLAPSIBLE_MAX_WIDTH_REM * baseFontSize;
-  }
-
-  function updateMobileLayout(width: number): void {
+}
+function updateMobileLayout(width) {
     if (!Number.isFinite(width) || width <= 0) {
-      return;
+        return;
     }
     isMobileLayout = width <= getCollapsibleMaxWidthPx();
-  }
-
-  $effect(() => {
+}
+$effect(() => {
     if (!isCollapsible || !navigationBarElement) {
-      isMobileLayout = false;
-      return;
+        isMobileLayout = false;
+        return;
     }
-
     if (typeof ResizeObserver === 'undefined') {
-      // Fallback: use border-box width if ResizeObserver unavailable
-      const initialWidth = navigationBarElement.getBoundingClientRect().width;
-      updateMobileLayout(initialWidth);
-      return;
+        // Fallback: use border-box width if ResizeObserver unavailable
+        const initialWidth = navigationBarElement.getBoundingClientRect().width;
+        updateMobileLayout(initialWidth);
+        return;
     }
-
     // Use ResizeObserver to track content-box width, which aligns with CSS container queries.
     // Don't read initial width synchronously; let observer fire immediately on observe().
     let hasInitialMeasurement = false;
-
     const observer = new ResizeObserver((entries) => {
-      const entry = entries[0];
-      if (!entry) {
-        return;
-      }
-      updateMobileLayout(entry.contentRect.width);
-      hasInitialMeasurement = true;
+        const entry = entries[0];
+        if (!entry) {
+            return;
+        }
+        updateMobileLayout(entry.contentRect.width);
+        hasInitialMeasurement = true;
     });
-
     observer.observe(navigationBarElement);
-
     // If observer doesn't fire synchronously (edge case), set a fallback after a microtask.
     // In modern browsers, observe() triggers callback synchronously on the same tick.
     if (!hasInitialMeasurement) {
-      Promise.resolve().then(() => {
-        if (!hasInitialMeasurement) {
-          // Fallback: measure once more using contentRect-like calculation
-          const rect = navigationBarElement?.getBoundingClientRect();
-          const styles = navigationBarElement ? getComputedStyle(navigationBarElement) : null;
-          if (rect && styles) {
-            const paddingLeft = Number.parseFloat(styles.paddingLeft) || 0;
-            const paddingRight = Number.parseFloat(styles.paddingRight) || 0;
-            const contentWidth = rect.width - paddingLeft - paddingRight;
-            updateMobileLayout(contentWidth);
-            hasInitialMeasurement = true;
-          }
-        }
-      });
+        Promise.resolve().then(() => {
+            if (!hasInitialMeasurement) {
+                // Fallback: measure once more using contentRect-like calculation
+                const rect = navigationBarElement?.getBoundingClientRect();
+                const styles = navigationBarElement ? getComputedStyle(navigationBarElement) : null;
+                if (rect && styles) {
+                    const paddingLeft = Number.parseFloat(styles.paddingLeft) || 0;
+                    const paddingRight = Number.parseFloat(styles.paddingRight) || 0;
+                    const contentWidth = rect.width - paddingLeft - paddingRight;
+                    updateMobileLayout(contentWidth);
+                    hasInitialMeasurement = true;
+                }
+            }
+        });
     }
-
     return () => {
-      observer.disconnect();
+        observer.disconnect();
     };
-  });
-
-  function handleToggle(event: MouseEvent): void {
+});
+function handleToggle(event) {
     mobileMenuOpen = !mobileMenuOpen;
-    toggleElement = event.currentTarget as HTMLElement | null;
-  }
-
-  function getNavigationItems(): HTMLElement[] {
-    if (!itemsRegionElement) return [];
-
-    return Array.from(itemsRegionElement.querySelectorAll<HTMLElement>(navigationItemSelector));
-  }
-
-  function isEnabledNavigationItem(item: HTMLElement): boolean {
+    toggleElement = event.currentTarget;
+}
+function getNavigationItems() {
+    if (!itemsRegionElement)
+        return [];
+    return Array.from(itemsRegionElement.querySelectorAll(navigationItemSelector));
+}
+function isEnabledNavigationItem(item) {
     return item.getAttribute('aria-disabled') !== 'true' && !item.hasAttribute('disabled');
-  }
-
-  function getEventNavigationItem(event: KeyboardEvent): HTMLElement | null {
-    if (!(event.target instanceof HTMLElement) || !itemsRegionElement) return null;
-
-    const navigationItem = event.target.closest<HTMLElement>(navigationItemSelector);
-    if (!navigationItem || !itemsRegionElement.contains(navigationItem)) return null;
-    if (navigationItem !== event.target) return null;
-
+}
+function getEventNavigationItem(event) {
+    if (!(event.target instanceof HTMLElement) || !itemsRegionElement)
+        return null;
+    const navigationItem = event.target.closest(navigationItemSelector);
+    if (!navigationItem || !itemsRegionElement.contains(navigationItem))
+        return null;
+    if (navigationItem !== event.target)
+        return null;
     return navigationItem;
-  }
-
-  function focusAdjacentNavigationItem(currentItem: HTMLElement, direction: -1 | 1): void {
+}
+function focusAdjacentNavigationItem(currentItem, direction) {
     const items = getNavigationItems();
-    if (items.length === 0) return;
-
+    if (items.length === 0)
+        return;
     const currentIndex = items.indexOf(currentItem);
-    if (currentIndex === -1) return;
-
-    for (let step = 1; step < items.length; step++) {
-      const nextIndex = (currentIndex + direction * step + items.length) % items.length;
-      const nextItem = items[nextIndex];
-      if (nextItem && isEnabledNavigationItem(nextItem)) {
-        nextItem.focus();
+    if (currentIndex === -1)
         return;
-      }
+    for (let step = 1; step < items.length; step++) {
+        const nextIndex = (currentIndex + direction * step + items.length) % items.length;
+        const nextItem = items[nextIndex];
+        if (nextItem && isEnabledNavigationItem(nextItem)) {
+            nextItem.focus();
+            return;
+        }
     }
-  }
-
-  function handleKeyDown(event: KeyboardEvent): void {
+}
+function handleKeyDown(event) {
     // Consumer handler runs first; if it cancels, skip the internal close.
     if (consumerOnKeyDown) {
-      (consumerOnKeyDown as (e: KeyboardEvent) => void)(event);
+        consumerOnKeyDown(event);
     }
-    if (event.defaultPrevented) return;
-
+    if (event.defaultPrevented)
+        return;
     if (event.key === 'Escape' && isCollapsible && isMobileLayout && mobileMenuOpen) {
-      mobileMenuOpen = false;
-      // Return focus synchronously — toggleElement is captured on each click.
-      toggleElement?.focus();
-      return;
+        mobileMenuOpen = false;
+        // Return focus synchronously — toggleElement is captured on each click.
+        toggleElement?.focus();
+        return;
     }
-
     const navigationItem = getEventNavigationItem(event);
-    if (!navigationItem) return;
-
+    if (!navigationItem)
+        return;
     if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
-      event.preventDefault();
-      focusAdjacentNavigationItem(navigationItem, event.key === 'ArrowRight' ? 1 : -1);
-      return;
+        event.preventDefault();
+        focusAdjacentNavigationItem(navigationItem, event.key === 'ArrowRight' ? 1 : -1);
+        return;
     }
-
     if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
-      event.preventDefault();
-      if (isEnabledNavigationItem(navigationItem)) {
-        navigationItem.click();
-      }
+        event.preventDefault();
+        if (isEnabledNavigationItem(navigationItem)) {
+            navigationItem.click();
+        }
     }
-  }
+}
 </script>
 
 <nav
@@ -219,15 +158,26 @@
   data-collapsible={isCollapsible ? 'true' : 'false'}
   data-cinder-placement={placement}
   data-cinder-label-visibility={showLabels}
+  data-cinder-menu-toggle-placement={menuTogglePlacement}
   onkeydown={handleKeyDown}
 >
+  {#if isCollapsible && menuToggle && menuTogglePlacement === 'before-brand'}
+    <div class="cinder-navigation-bar__menu-toggle">
+      {@render menuToggle({
+        'aria-expanded': (mobileMenuOpen ? 'true' : 'false') as 'true' | 'false',
+        'aria-controls': regionId,
+        ...(browser ? { onclick: handleToggle } : {}),
+      })}
+    </div>
+  {/if}
+
   {#if brand}
     <div class="cinder-navigation-bar__brand">
       {@render brand()}
     </div>
   {/if}
 
-  {#if isCollapsible && menuToggle}
+  {#if isCollapsible && menuToggle && menuTogglePlacement === 'after-brand'}
     <div class="cinder-navigation-bar__menu-toggle">
       {@render menuToggle({
         'aria-expanded': (mobileMenuOpen ? 'true' : 'false') as 'true' | 'false',

package/src/components/navigation-bar/navigation-bar.types.ts

@@ -3,6 +3,7 @@ import type { HTMLAttributes } from 'svelte/elements';
 export type NavigationVariant = 'horizontal' | 'mobile';
 export type NavigationBarPlacement = 'top' | 'bottom';
 export type NavigationBarLabelVisibility = 'always' | 'active' | 'never';
+export type NavigationBarMenuTogglePlacement = 'after-brand' | 'before-brand';
 /** Attributes injected into the consumer's toggle button via the menuToggle snippet parameter. */
 export type NavigationBarToggleAttributes = {
   'aria-expanded': 'true' | 'false';
@@ -33,6 +34,13 @@ export type NavigationBarProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
    * @default "always"
    */
   showLabels?: NavigationBarLabelVisibility;
+  /**
+   * Placement for the collapsible mobile menu toggle in top navigation bars.
+   * Ignored for `placement="bottom"`.
+   *
+   * @default "after-brand"
+   */
+  menuTogglePlacement?: NavigationBarMenuTogglePlacement;
   brand?: Snippet;
   /** Receives a context object with the current variant. */
   items: Snippet<[NavigationBarItemsContext]>;

package/src/components/navigation-bar/navigation-bar.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/navigation-bar/navigation-bar.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/navigation-item/navigation-item.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "active": {
+      "type": "boolean",
+      "description": "Marks this item as the currently active destination; emits `aria-current` and applies active visual styling."
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Prevents interaction: removes the item from the tab order, blocks clicks, and applies disabled visual styling."
+    },
+    "current": {
+      "enum": ["true", "page", "step", "location", "date", "time"],
+      "description": "The `aria-current` token emitted while `active` is true. Defaults to `'page'`,\nwhich is correct for navigation bars and breadcrumb-adjacent links. Use\n`'true'` (or another standard token such as `'step'` / `'location'`) for\nsection/view switchers, where `'page'` would mislabel the current section as\nthe current page in the browsing context."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class merged onto the `.cinder-navigation-item` root element."
+    },
+    "variant": {
+      "enum": ["horizontal", "vertical", "mobile"],
+      "description": "Controls item geometry. Emitted as `data-variant`. Default `'horizontal'`.\n\n- `'horizontal'`: top-rounded radius, accent bottom-border active indicator.\n  Used inside `NavigationBar` and similar horizontal tab-bar contexts.\n- `'mobile'`: stacked full-width layout when an owning navigation surface\n  enters its narrow container mode.\n- `'vertical'`: square row geometry, neutral selected surface, and accent inline-start border active indicator.\n  Used inside `SideNavigation` (set automatically by `SideNavigationItem`) or\n  standalone sidebar footers where flush sidebar edges are required."
+    },
+    "href": {
+      "type": "string",
+      "description": "Destination URL. Providing this prop renders the item as an `<a>` element instead of a `<button>`."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet",
+        "required": true
+      },
+      {
+        "name": "onclick",
+        "reason": "function-or-snippet",
+        "description": "Optional click handler called for the rendered `<a>` element. Useful for\nintercepting plain left-clicks for SPA navigation while letting modified\nclicks (cmd/ctrl/shift/alt or middle-click) fall through to native browser\nbehavior. Disabled-state preventDefault still applies."
+      }
+    ]
+  }
+}

package/src/components/navigation-item/navigation-item.schema.ts

@@ -0,0 +1,55 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    active: {
+      type: 'boolean',
+      description:
+        'Marks this item as the currently active destination; emits `aria-current` and applies active visual styling.',
+    },
+    disabled: {
+      type: 'boolean',
+      description:
+        'Prevents interaction: removes the item from the tab order, blocks clicks, and applies disabled visual styling.',
+    },
+    current: {
+      enum: ['true', 'page', 'step', 'location', 'date', 'time'],
+      description:
+        "The `aria-current` token emitted while `active` is true. Defaults to `'page'`,\nwhich is correct for navigation bars and breadcrumb-adjacent links. Use\n`'true'` (or another standard token such as `'step'` / `'location'`) for\nsection/view switchers, where `'page'` would mislabel the current section as\nthe current page in the browsing context.",
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class merged onto the `.cinder-navigation-item` root element.',
+    },
+    variant: {
+      enum: ['horizontal', 'vertical', 'mobile'],
+      description:
+        "Controls item geometry. Emitted as `data-variant`. Default `'horizontal'`.\n\n- `'horizontal'`: top-rounded radius, accent bottom-border active indicator.\n  Used inside `NavigationBar` and similar horizontal tab-bar contexts.\n- `'mobile'`: stacked full-width layout when an owning navigation surface\n  enters its narrow container mode.\n- `'vertical'`: square row geometry, neutral selected surface, and accent inline-start border active indicator.\n  Used inside `SideNavigation` (set automatically by `SideNavigationItem`) or\n  standalone sidebar footers where flush sidebar edges are required.",
+    },
+    href: {
+      type: 'string',
+      description:
+        'Destination URL. Providing this prop renders the item as an `<a>` element instead of a `<button>`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+      },
+      {
+        name: 'onclick',
+        reason: 'function-or-snippet',
+        description:
+          'Optional click handler called for the rendered `<a>` element. Useful for\nintercepting plain left-clicks for SPA navigation while letting modified\nclicks (cmd/ctrl/shift/alt or middle-click) fall through to native browser\nbehavior. Disabled-state preventDefault still applies.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;