@lostgradient/cinder 0.12.0 → 0.13.0

package/src/components/segment/segment.schema.ts

@@ -1,50 +1,8 @@
 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 with `.cinder-segmented-control-option`.',
-    },
-    disabled: {
-      type: 'boolean',
-      description: 'Disable just this segment (independent of the control-level `disabled`).',
-    },
-    controls: {
-      type: 'string',
-      description:
-        'ID of the panel this segment controls — only meaningful when the parent\n`SegmentedControl` uses `variant="tablist"`.',
-    },
-  },
-  additionalProperties: false,
-  metadata: {
-    unsupportedProps: [
-      {
-        name: 'children',
-        reason: 'function-or-snippet',
-        required: true,
-        description: "The segment's label content.",
-      },
-      {
-        name: 'leading',
-        reason: 'function-or-snippet',
-        description: 'Optional decorative content rendered before the label, inside `aria-hidden`.',
-      },
-      {
-        name: 'trailing',
-        reason: 'function-or-snippet',
-        description: 'Optional decorative content rendered after the label, inside `aria-hidden`.',
-      },
-      {
-        name: 'value',
-        reason: 'unknown-shape',
-        required: true,
-        description: 'Value this segment represents. Must be unique within the parent control.',
-      },
-    ],
-  },
-} satisfies ComponentSchema;
+// eslint-disable-next-line no-unsafe-type-assertion -- generated schema parsed from a build-validated JSON string; see generate-component-schema.ts.
+const schema = JSON.parse(
+  '{\n  "$schema": "https://json-schema.org/draft/2020-12/schema",\n  "type": "object",\n  "properties": {\n    "class": {\n      "type": "string",\n      "description": "Custom class merged with `.cinder-segmented-control-option`."\n    },\n    "disabled": {\n      "type": "boolean",\n      "description": "Disable just this segment (independent of the control-level `disabled`)."\n    },\n    "href": {\n      "type": "string",\n      "description": "Render this segment as a real link inside `SegmentedControl variant=\\"navigation\\"`."\n    },\n    "current": {\n      "type": "boolean",\n      "description": "Marks this linked segment as the current route/filter."\n    },\n    "currentToken": {\n      "enum": [\n        "page",\n        "step",\n        "location",\n        "date",\n        "time",\n        "true"\n      ],\n      "description": "`aria-current` token emitted while `current` is true. Defaults to `\\"page\\"`."\n    },\n    "value": {\n      "type": "string",\n      "description": "Value this segment represents. Required when `href` is not provided."\n    },\n    "controls": {\n      "type": "string",\n      "description": "ID of the panel this segment controls — only meaningful when the parent\\n`SegmentedControl` uses `variant=\\"tablist\\"`."\n    }\n  },\n  "additionalProperties": false,\n  "metadata": {\n    "unsupportedProps": [\n      {\n        "name": "children",\n        "reason": "function-or-snippet",\n        "required": true,\n        "description": "The segment\'s label content."\n      },\n      {\n        "name": "leading",\n        "reason": "function-or-snippet",\n        "description": "Optional decorative content rendered before the label, inside `aria-hidden`."\n      },\n      {\n        "name": "onclick",\n        "reason": "function-or-snippet",\n        "description": "Optional click handler for the rendered link. Disabled navigation segments\\nprevent default and do not call this handler."\n      },\n      {\n        "name": "trailing",\n        "reason": "function-or-snippet",\n        "description": "Optional decorative content rendered after the label, inside `aria-hidden`."\n      }\n    ]\n  },\n  "allOf": [\n    {\n      "if": {\n        "not": {\n          "required": [\n            "href"\n          ]\n        }\n      },\n      "then": {\n        "required": [\n          "value"\n        ]\n      }\n    }\n  ]\n}',
+) as ComponentSchema;
 
-export default schema as ComponentSchema;
+export default schema;

package/src/components/segment/segment.svelte

@@ -6,8 +6,9 @@ export {};
 import { untrack } from 'svelte';
 import { classNames } from '../../utilities/class-names.ts';
 import { getSegmentedControlContext } from '../segmented-control/segmented-control-state.svelte.ts';
-let { value, disabled = false, controls, leading, trailing, children, class: customClassName, ...rest } = $props();
+let { value, href, download, target, rel, current = false, currentToken = 'page', disabled = false, controls, leading, trailing, children, class: customClassName, onclick, ...rest } = $props();
 const context = getSegmentedControlContext();
+const buttonValue = $derived(value ?? href ?? '');
 const registerSegment = (node) => {
     // Attachments run inside a tracked effect. Wrap the call to register() in
     // `untrack` so the controller's mutation of its internal state does not
@@ -18,7 +19,7 @@ const registerSegment = (node) => {
     return untrack(() => context.register({
         node,
         get value() {
-            return value;
+            return buttonValue;
         },
         get disabled() {
             return disabled || context.controlDisabled;
@@ -28,34 +29,28 @@ const registerSegment = (node) => {
         },
     }));
 };
-const isSelected = $derived(context.isSelected(value));
-const isFocusable = $derived(context.isFocusable(value));
+const isSelected = $derived(context.isSelected(buttonValue));
+const isFocusable = $derived(context.isFocusable(buttonValue));
 const effectiveDisabled = $derived(disabled || context.controlDisabled);
+const isNavigationItem = $derived(context.variant === 'navigation');
+const anchorDisabled = $derived(effectiveDisabled || href === undefined);
+const elementAttributes = $derived(rest);
+const anchorTabindex = $derived(anchorDisabled ? -1 : elementAttributes.tabindex);
 const role = $derived(context.selectionMode === 'multiple'
     ? undefined
     : context.variant === 'tablist'
         ? 'tab'
         : 'radio');
+function handleAnchorClick(event) {
+    if (anchorDisabled) {
+        event.preventDefault();
+        return;
+    }
+    onclick?.(event);
+}
 </script>
 
-<button
-  {...rest}
-  type="button"
-  {role}
-  data-cinder-segment-value={value}
-  aria-checked={role === 'radio' ? isSelected : undefined}
-  aria-selected={role === 'tab' ? isSelected : undefined}
-  aria-pressed={context.selectionMode === 'multiple' ? isSelected : undefined}
-  aria-controls={role === 'tab' ? controls : undefined}
-  aria-disabled={effectiveDisabled ? 'true' : undefined}
-  disabled={context.selectionMode === 'multiple' ? effectiveDisabled : undefined}
-  tabindex={isFocusable ? 0 : -1}
-  class={classNames('cinder-segmented-control-option', customClassName)}
-  data-cinder-selected={isSelected ? '' : undefined}
-  data-cinder-pressed={context.selectionMode === 'multiple' && isSelected ? '' : undefined}
-  onclick={() => context.toggle(value)}
-  {@attach registerSegment}
->
+{#snippet content()}
   {#if leading}
     <span class="cinder-segmented-control-option-icon" aria-hidden="true">
       {@render leading()}
@@ -70,4 +65,44 @@ const role = $derived(context.selectionMode === 'multiple'
       {@render trailing()}
     </span>
   {/if}
-</button>
+{/snippet}
+
+{#if isNavigationItem}
+  <a
+    {...elementAttributes}
+    href={anchorDisabled ? undefined : href}
+    {download}
+    {target}
+    {rel}
+    data-cinder-segment-value={buttonValue}
+    aria-current={current ? currentToken : undefined}
+    aria-disabled={anchorDisabled ? 'true' : undefined}
+    tabindex={anchorTabindex}
+    class={classNames('cinder-segmented-control-option', customClassName)}
+    data-cinder-current={current ? '' : undefined}
+    onclick={handleAnchorClick}
+  >
+    {@render content()}
+  </a>
+{:else}
+  <button
+    {...elementAttributes}
+    type="button"
+    {role}
+    data-cinder-segment-value={buttonValue}
+    aria-checked={role === 'radio' ? isSelected : undefined}
+    aria-selected={role === 'tab' ? isSelected : undefined}
+    aria-pressed={context.selectionMode === 'multiple' ? isSelected : undefined}
+    aria-controls={role === 'tab' ? controls : undefined}
+    aria-disabled={effectiveDisabled ? 'true' : undefined}
+    disabled={context.selectionMode === 'multiple' ? effectiveDisabled : undefined}
+    tabindex={isFocusable ? 0 : -1}
+    class={classNames('cinder-segmented-control-option', customClassName)}
+    data-cinder-selected={isSelected ? '' : undefined}
+    data-cinder-pressed={context.selectionMode === 'multiple' && isSelected ? '' : undefined}
+    onclick={() => context.toggle(buttonValue)}
+    {@attach registerSegment}
+  >
+    {@render content()}
+  </button>
+{/if}

package/src/components/segment/segment.types.ts

@@ -1,39 +1,109 @@
 import type { Snippet } from 'svelte';
-import type { HTMLButtonAttributes } from 'svelte/elements';
+import type { HTMLAnchorAttributes, HTMLAttributes } from 'svelte/elements';
+
+export type SegmentCurrentToken = 'page' | 'step' | 'location' | 'date' | 'time' | 'true';
 
 // Attributes the component owns and computes itself, so a consumer value would
 // be silently overridden. `onfocus` / `onblur` are intentionally NOT here: the
 // component implements no focus handling, so forwarding them through `...rest`
 // lets consumers wire focus-driven behavior (tooltips, analytics) on a segment.
+type SharedProps = {
+  /** Custom class merged with `.cinder-segmented-control-option`. */
+  class?: string | undefined;
+  /** Disable just this segment (independent of the control-level `disabled`). */
+  disabled?: boolean | undefined;
+  /** Optional decorative content rendered before the label, inside `aria-hidden`. */
+  leading?: Snippet | undefined;
+  /** Optional decorative content rendered after the label, inside `aria-hidden`. */
+  trailing?: Snippet | undefined;
+  /** The segment's label content. */
+  children: Snippet;
+};
+
 type SegmentOwnedAttributes =
   | 'role'
   | 'type'
   | 'disabled'
   | 'tabindex'
   | 'class'
+  | 'href'
+  | 'download'
+  | 'target'
+  | 'rel'
   | 'aria-checked'
   | 'aria-selected'
   | 'aria-pressed'
   | 'aria-controls'
   | 'aria-disabled'
+  | 'aria-current'
   | 'onclick';
 
-export type SegmentProps = Omit<HTMLButtonAttributes, SegmentOwnedAttributes> & {
-  /** Value this segment represents. Must be unique within the parent control. */
-  value: string;
+type SharedElementAttributes = Omit<HTMLAttributes<HTMLElement>, SegmentOwnedAttributes>;
+
+type SegmentButtonProps = SharedElementAttributes &
+  SharedProps & {
+    href?: undefined;
+    download?: undefined;
+    target?: undefined;
+    rel?: undefined;
+    current?: undefined;
+    currentToken?: undefined;
+    onclick?: undefined;
+    /** Value this segment represents. Must be unique within the parent control. */
+    value: string;
+    /**
+     * ID of the panel this segment controls — only meaningful when the parent
+     * `SegmentedControl` uses `variant="tablist"`.
+     */
+    controls?: string | undefined;
+  };
+
+type SegmentAnchorProps = SharedElementAttributes &
+  SharedProps & {
+    /** Render this segment as a real link inside `SegmentedControl variant="navigation"`. */
+    href: string;
+    /** Download hint for the rendered link. */
+    download?: boolean | string | undefined;
+    /** Browsing context for the rendered link. */
+    target?: HTMLAnchorAttributes['target'] | undefined;
+    /** Relationship metadata for the rendered link. */
+    rel?: HTMLAnchorAttributes['rel'] | undefined;
+    /** Optional tab index for enabled links. Disabled navigation links force `-1`. */
+    tabindex?: HTMLAttributes<HTMLElement>['tabindex'] | undefined;
+    /**
+     * Optional click handler for the rendered link. Disabled navigation segments
+     * prevent default and do not call this handler.
+     */
+    onclick?: ((event: MouseEvent) => void) | undefined;
+    /** Marks this linked segment as the current route/filter. */
+    current?: boolean | undefined;
+    /** `aria-current` token emitted while `current` is true. Defaults to `"page"`. */
+    currentToken?: SegmentCurrentToken | undefined;
+    /** Optional value for consumer metadata; navigation segments do not bind selection state. */
+    value?: string | undefined;
+    /** Panel controls apply only to tab segments, not navigation links. */
+    controls?: undefined;
+  };
+
+export type SegmentProps = SegmentButtonProps | SegmentAnchorProps;
+
+/** Schema generator surface for Segment's cinder-specific, JSON-expressible props. */
+export interface SegmentSchemaProps {
   /** Custom class merged with `.cinder-segmented-control-option`. */
   class?: string | undefined;
   /** Disable just this segment (independent of the control-level `disabled`). */
   disabled?: boolean | undefined;
+  /** Render this segment as a real link inside `SegmentedControl variant="navigation"`. */
+  href?: string | undefined;
+  /** Marks this linked segment as the current route/filter. */
+  current?: boolean | undefined;
+  /** `aria-current` token emitted while `current` is true. Defaults to `"page"`. */
+  currentToken?: SegmentCurrentToken | undefined;
+  /** Value this segment represents. Required when `href` is not provided. */
+  value?: string | undefined;
   /**
    * ID of the panel this segment controls — only meaningful when the parent
    * `SegmentedControl` uses `variant="tablist"`.
    */
   controls?: string | undefined;
-  /** Optional decorative content rendered before the label, inside `aria-hidden`. */
-  leading?: Snippet | undefined;
-  /** Optional decorative content rendered after the label, inside `aria-hidden`. */
-  trailing?: Snippet | undefined;
-  /** The segment's label content. */
-  children: Snippet;
-};
+}

package/src/components/segmented-control/segmented-control.css

@@ -98,6 +98,7 @@
     cursor: pointer;
     font-weight: var(--cinder-font-medium);
     line-height: 1;
+    text-decoration: none;
     transition:
       background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
       color var(--cinder-duration-fast) var(--cinder-ease-standard),
@@ -117,11 +118,16 @@
 
   .cinder-segmented-control:not([data-cinder-detached])
     .cinder-segmented-control-option[data-cinder-selected]:not(:first-child)::before,
+  .cinder-segmented-control:not([data-cinder-detached])
+    .cinder-segmented-control-option[data-cinder-current]:not(:first-child)::before,
   .cinder-segmented-control:not([data-cinder-detached])
     .cinder-segmented-control-option[data-cinder-pressed]:not(:first-child)::before,
   .cinder-segmented-control:not([data-cinder-detached])
     [data-cinder-selected]
     + .cinder-segmented-control-option::before,
+  .cinder-segmented-control:not([data-cinder-detached])
+    [data-cinder-current]
+    + .cinder-segmented-control-option::before,
   .cinder-segmented-control:not([data-cinder-detached])
     [data-cinder-pressed]
     + .cinder-segmented-control-option::before {
@@ -211,9 +217,9 @@
   /* Sticky-hover suppression on touch: wrap hover-only chrome so it doesn't
  * "stick" after tap on touch devices that emulate :hover. */
   @media (hover: hover) {
-    .cinder-segmented-control-option:hover:not(:disabled):not([data-cinder-selected]):not(
-        [data-cinder-pressed]
-      ) {
+    .cinder-segmented-control-option:hover:not(:disabled):not([aria-disabled='true']):not(
+        [data-cinder-selected]
+      ):not([data-cinder-current]):not([data-cinder-pressed]) {
       background: color-mix(in oklch, var(--cinder-accent), transparent 90%);
       color: var(--cinder-text);
     }
@@ -229,6 +235,9 @@
     .cinder-segmented-control-option[data-cinder-selected]:hover:not(:disabled):not(
         [aria-disabled='true']
       ),
+    .cinder-segmented-control-option[data-cinder-current]:hover:not(:disabled):not(
+        [aria-disabled='true']
+      ),
     .cinder-segmented-control-option[data-cinder-pressed]:hover:not(:disabled):not(
         [aria-disabled='true']
       ) {
@@ -248,7 +257,8 @@
 
   /* ── Disabled option ────────────────────────────────────────────────────── */
 
-  .cinder-segmented-control-option:disabled {
+  .cinder-segmented-control-option:disabled,
+  .cinder-segmented-control-option[aria-disabled='true'] {
     cursor: not-allowed;
     /* opacity centralized in foundation.css disabled-visual rule (0.6) */
   }
@@ -261,6 +271,12 @@
     box-shadow: var(--cinder-shadow-sm);
   }
 
+  .cinder-segmented-control-option[data-cinder-current] {
+    background: var(--cinder-accent);
+    color: var(--cinder-accent-contrast);
+    box-shadow: var(--cinder-shadow-sm);
+  }
+
   .cinder-segmented-control-option-icon {
     opacity: 0.9;
   }
@@ -283,7 +299,9 @@
   .cinder-segmented-control:not([data-cinder-variant='tablist'])
     .cinder-segmented-control-option[data-cinder-selected]:focus-visible,
   .cinder-segmented-control:not([data-cinder-variant='tablist'])
-    .cinder-segmented-control-option[data-cinder-pressed]:focus-visible {
+    .cinder-segmented-control-option[data-cinder-pressed]:focus-visible,
+  .cinder-segmented-control:not([data-cinder-variant='tablist'])
+    .cinder-segmented-control-option[data-cinder-current]:focus-visible {
     box-shadow:
       0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
       0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
@@ -296,7 +314,9 @@
     .cinder-segmented-control:not([data-cinder-variant='tablist'])
       .cinder-segmented-control-option[data-cinder-selected]:focus-visible,
     .cinder-segmented-control:not([data-cinder-variant='tablist'])
-      .cinder-segmented-control-option[data-cinder-pressed]:focus-visible {
+      .cinder-segmented-control-option[data-cinder-pressed]:focus-visible,
+    .cinder-segmented-control:not([data-cinder-variant='tablist'])
+      .cinder-segmented-control-option[data-cinder-current]:focus-visible {
       outline: var(--cinder-ring-width) solid Highlight;
       outline-offset: 1px;
       box-shadow: none;

package/src/components/segmented-control/segmented-control.examples.json

@@ -15,6 +15,12 @@
       "description": "Multiple options can be toggled independently. Pass a SvelteSet to track selection.",
       "code": "<script lang=\"ts\">\n  import { SvelteSet } from 'svelte/reactivity';\n  import { Segment } from '@lostgradient/cinder/segment';\n  import { SegmentedControl } from '@lostgradient/cinder/segmented-control';\n\n  let formats = new SvelteSet<string>();\n\n  const selected = $derived([...formats].join(', ') || 'none');\n</script>\n\n<div style=\"display: grid; gap: 0.75rem; justify-items: start;\">\n  <SegmentedControl\n    id=\"playground-format\"\n    selectionMode=\"multiple\"\n    value={formats}\n    label=\"Text formatting\"\n  >\n    <Segment value=\"bold\">Bold</Segment>\n    <Segment value=\"italic\">Italic</Segment>\n    <Segment value=\"underline\">Underline</Segment>\n    <Segment value=\"strikethrough\">Strike</Segment>\n  </SegmentedControl>\n  <p style=\"margin: 0; color: var(--cinder-text-muted);\">Active formats: {selected}</p>\n</div>\n"
     },
+    {
+      "id": "navigation",
+      "title": "Navigation route filters",
+      "description": "Use the navigation variant with linked segments when each option should update the URL.",
+      "code": "<script lang=\"ts\">\n  import { Segment } from '@lostgradient/cinder/segment';\n  import { SegmentedControl } from '@lostgradient/cinder/segmented-control';\n\n  const sources = [\n    { label: 'Actual', href: '/costs?source=actual', current: true },\n    { label: 'Forecast', href: '/costs?source=forecast' },\n    { label: 'Blended', href: '/costs?source=blended' },\n  ];\n</script>\n\n<SegmentedControl id=\"cost-source-filter\" label=\"Cost source\" variant=\"navigation\">\n  {#each sources as source (source.href)}\n    <Segment href={source.href} current={source.current}>{source.label}</Segment>\n  {/each}\n</SegmentedControl>\n"
+    },
     {
       "id": "sizing",
       "title": "Sizing — size vs. toolbar density",

package/src/components/segmented-control/segmented-control.schema.json

@@ -43,8 +43,8 @@
       "description": "Stretch the control to fill available width."
     },
     "variant": {
-      "enum": ["radiogroup", "tablist"],
-      "description": "ARIA interaction pattern. Use `tablist` when options switch visible panels."
+      "enum": ["radiogroup", "tablist", "navigation"],
+      "description": "ARIA interaction pattern. Use `navigation` for route-backed links."
     },
     "class": {
       "type": "string",

package/src/components/segmented-control/segmented-control.schema.ts

@@ -48,8 +48,8 @@ const schema = {
       description: 'Stretch the control to fill available width.',
     },
     variant: {
-      enum: ['radiogroup', 'tablist'],
-      description: 'ARIA interaction pattern. Use `tablist` when options switch visible panels.',
+      enum: ['radiogroup', 'tablist', 'navigation'],
+      description: 'ARIA interaction pattern. Use `navigation` for route-backed links.',
     },
     class: {
       type: 'string',

package/src/components/segmented-control/segmented-control.svelte

@@ -12,9 +12,11 @@ let resetInputElement = $state(null);
 let resetSyncTimeout;
 const initialSingleValue = untrack(() => (typeof value === 'string' ? value : undefined));
 const initialMultipleValues = untrack(() => selectionMode === 'multiple' && value instanceof SvelteSet ? Array.from(value) : undefined);
+const effectiveVariant = $derived(selectionMode === 'multiple' && variant !== 'radiogroup' ? 'radiogroup' : variant);
+const rendersNavigation = $derived(effectiveVariant === 'navigation');
 const controller = new SegmentedControlController({
     selectionMode: () => selectionMode,
-    variant: () => variant,
+    variant: () => effectiveVariant,
     orientation: () => orientation,
     controlDisabled: () => disabled,
     disallowEmptySelection: () => disallowEmptySelection,
@@ -29,7 +31,7 @@ const contextValue = {
         return selectionMode;
     },
     get variant() {
-        return variant;
+        return effectiveVariant;
     },
     get controlDisabled() {
         return disabled;
@@ -41,7 +43,13 @@ const contextValue = {
 };
 setSegmentedControlContext(contextValue);
 // See docs/decisions/segmented-control-tablist-variant.md for why tablist remains a SegmentedControl variant.
-const groupRole = $derived(selectionMode === 'multiple' ? 'group' : variant === 'tablist' ? 'tablist' : 'radiogroup');
+const groupRole = $derived(selectionMode === 'multiple'
+    ? 'group'
+    : variant === 'navigation'
+        ? undefined
+        : variant === 'tablist'
+            ? 'tablist'
+            : 'radiogroup');
 // When density="toolbar" is requested it resolves to the compact `sm` visual
 // size — explicit `size` values are ignored while toolbar density is on so
 // toolbars line up with sibling toolbar controls. `data-cinder-size` reflects
@@ -94,26 +102,45 @@ $effect(() => {
   >
     {label}
   </span>
-  <div
-    {...rest}
-    {id}
-    role={groupRole}
-    aria-labelledby={`${id}-label`}
-    aria-disabled={disabled ? 'true' : undefined}
-    aria-orientation={selectionMode === 'single' ? orientation : undefined}
-    data-cinder-orientation={orientation}
-    data-cinder-size={effectiveSize}
-    data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
-    data-cinder-selection-mode={selectionMode}
-    data-cinder-detached={detached ? '' : undefined}
-    data-cinder-full-width={fullWidth ? '' : undefined}
-    data-cinder-variant={variant}
-    class={classNames('cinder-segmented-control', customClassName)}
-    onkeydown={(event) => controller.handleKeydown(event)}
-  >
-    {@render children()}
-  </div>
-  {#if name}
+  {#if rendersNavigation}
+    <nav
+      {...rest}
+      {id}
+      role="navigation"
+      aria-labelledby={`${id}-label`}
+      data-cinder-orientation={orientation}
+      data-cinder-size={effectiveSize}
+      data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
+      data-cinder-selection-mode={selectionMode}
+      data-cinder-detached={detached ? '' : undefined}
+      data-cinder-full-width={fullWidth ? '' : undefined}
+      data-cinder-variant={effectiveVariant}
+      class={classNames('cinder-segmented-control', customClassName)}
+    >
+      {@render children()}
+    </nav>
+  {:else}
+    <div
+      {...rest}
+      {id}
+      role={groupRole}
+      aria-labelledby={`${id}-label`}
+      aria-disabled={disabled ? 'true' : undefined}
+      aria-orientation={selectionMode === 'single' ? orientation : undefined}
+      data-cinder-orientation={orientation}
+      data-cinder-size={effectiveSize}
+      data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
+      data-cinder-selection-mode={selectionMode}
+      data-cinder-detached={detached ? '' : undefined}
+      data-cinder-full-width={fullWidth ? '' : undefined}
+      data-cinder-variant={effectiveVariant}
+      class={classNames('cinder-segmented-control', customClassName)}
+      onkeydown={(event) => controller.handleKeydown(event)}
+    >
+      {@render children()}
+    </div>
+  {/if}
+  {#if name && !rendersNavigation}
     <input bind:this={resetInputElement} type="hidden" disabled />
     {#each selectedValues as selectedValue (selectedValue)}
       <input type="hidden" {name} value={selectedValue} {disabled} />

package/src/components/segmented-control/segmented-control.types.ts

@@ -14,10 +14,7 @@ type ComponentOwnedAttributes =
   | 'onchange'
   | 'onkeydown';
 
-type CommonProps<T extends string> = Omit<
-  HTMLAttributes<HTMLDivElement>,
-  ComponentOwnedAttributes
-> & {
+type CommonProps<T extends string> = Omit<HTMLAttributes<HTMLElement>, ComponentOwnedAttributes> & {
   /** Unique identifier for the control. */
   id: string;
   /** Accessible label for the group. */
@@ -53,8 +50,8 @@ type CommonProps<T extends string> = Omit<
   detached?: boolean | undefined;
   /** Stretch the control to fill available width. */
   fullWidth?: boolean | undefined;
-  /** ARIA interaction pattern. Use `tablist` when options switch visible panels. */
-  variant?: 'radiogroup' | 'tablist' | undefined;
+  /** ARIA interaction pattern. Use `navigation` for route-backed links. */
+  variant?: 'radiogroup' | 'tablist' | 'navigation' | undefined;
   /** Additional class names merged with `.cinder-segmented-control`. */
   class?: string | undefined;
   /** Called when the selected value changes (single mode only). */
@@ -82,7 +79,7 @@ type MultipleProps<T extends string> = CommonProps<T> & {
   value?: SvelteSet<T> | undefined;
   /** Not applicable in multiple mode — present for Svelte destructuring compatibility. */
   disallowEmptySelection?: undefined;
-  /** Tablist semantics are only valid for single selection. */
+  /** Tablist and navigation semantics are only valid for single selection. */
   variant?: 'radiogroup' | undefined;
 };
 

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

@@ -13,6 +13,7 @@
  * ======================================== */
 
   .cinder-side-navigation {
+    --cinder-side-navigation-list-gap: var(--cinder-space-1);
     display: block;
   }
 
@@ -22,7 +23,7 @@
     padding: 0;
     display: flex;
     flex-direction: column;
-    gap: var(--cinder-space-1);
+    gap: var(--cinder-side-navigation-list-gap, var(--cinder-space-1));
   }
 
   /* ----------------------------------------

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

@@ -9,6 +9,12 @@
       "description": "A grouped sidebar nav. Uses the SideNavigation namespace API: SideNavigation.Group wraps a collapsible section and SideNavigation.Item renders each link.",
       "code": "<script lang=\"ts\">\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n</script>\n\n<SideNavigation ariaLabel=\"Workspace\">\n  <SideNavigation.Item href=\"/dashboard\">Dashboard</SideNavigation.Item>\n  <SideNavigation.Group label=\"Projects\">\n    <SideNavigation.Item href=\"/projects/phoenix\" active>Phoenix</SideNavigation.Item>\n    <SideNavigation.Item href=\"/projects/atlas\">Atlas</SideNavigation.Item>\n    <SideNavigation.Item href=\"/projects/beacon\">Beacon</SideNavigation.Item>\n  </SideNavigation.Group>\n  <SideNavigation.Group label=\"Settings\">\n    <SideNavigation.Item href=\"/settings/team\">Team</SideNavigation.Item>\n    <SideNavigation.Item href=\"/settings/billing\">Billing</SideNavigation.Item>\n  </SideNavigation.Group>\n</SideNavigation>\n"
     },
+    {
+      "id": "compact-sidebar",
+      "title": "Compact sidebar spacing",
+      "description": "Dense sidebars can tune the SideNavigation list gap through a public CSS variable.",
+      "code": "<script lang=\"ts\">\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n</script>\n\n<div style=\"max-inline-size: 18rem;\">\n  <SideNavigation ariaLabel=\"Inspector sections\" style=\"--cinder-side-navigation-list-gap: 0;\">\n    <SideNavigation.Item href=\"#overview\" active>Overview</SideNavigation.Item>\n    <SideNavigation.Item href=\"#timeline\">Timeline</SideNavigation.Item>\n    <SideNavigation.Item href=\"#payload\">Payload</SideNavigation.Item>\n    <SideNavigation.Group label=\"Artifacts\">\n      <SideNavigation.Item href=\"#source\">Source</SideNavigation.Item>\n      <SideNavigation.Item href=\"#snapshot\">Snapshot</SideNavigation.Item>\n    </SideNavigation.Group>\n  </SideNavigation>\n</div>\n"
+    },
     {
       "id": "docs-sidebar",
       "title": "Docs sidebar",

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

@@ -5,6 +5,14 @@
     "ariaLabel": {
       "type": "string",
       "description": "Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional CSS class merged with `.cinder-side-navigation`."
+    },
+    "style": {
+      "type": "string",
+      "description": "Inline style string applied to the `.cinder-side-navigation` root."
     }
   },
   "additionalProperties": false,
@@ -16,11 +24,6 @@
         "reason": "function-or-snippet",
         "required": true,
         "description": "Must be <li> elements containing NavigationItem and/or SideNavigationGroup."
-      },
-      {
-        "name": "class",
-        "reason": "unknown-shape",
-        "description": "Additional CSS class merged with `.cinder-side-navigation`."
       }
     ]
   }

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

@@ -9,6 +9,14 @@ const schema = {
       description:
         'Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page.',
     },
+    class: {
+      type: 'string',
+      description: 'Additional CSS class merged with `.cinder-side-navigation`.',
+    },
+    style: {
+      type: 'string',
+      description: 'Inline style string applied to the `.cinder-side-navigation` root.',
+    },
   },
   additionalProperties: false,
   required: ['ariaLabel'],
@@ -20,11 +28,6 @@ const schema = {
         required: true,
         description: 'Must be <li> elements containing NavigationItem and/or SideNavigationGroup.',
       },
-      {
-        name: 'class',
-        reason: 'unknown-shape',
-        description: 'Additional CSS class merged with `.cinder-side-navigation`.',
-      },
     ],
   },
 } satisfies ComponentSchema;