@lostgradient/cinder 0.1.1 → 0.3.0

package/src/components/capability-gate/capability-gate.css

@@ -0,0 +1,134 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-capability-gate {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-2);
+    padding: var(--cinder-space-3);
+    border-radius: var(--cinder-radius-md);
+    border: 1px solid var(--cinder-border);
+    background-color: var(--cinder-surface);
+    color: var(--cinder-text);
+  }
+
+  /* Variant-based color theming */
+  .cinder-capability-gate[data-cinder-variant='error'] {
+    border-color: var(--cinder-color-danger-border);
+    background-color: var(--cinder-color-danger-bg);
+  }
+
+  .cinder-capability-gate[data-cinder-variant='warning'] {
+    border-color: var(--cinder-color-warning-border);
+    background-color: var(--cinder-color-warning-bg);
+  }
+
+  .cinder-capability-gate[data-cinder-variant='success'] {
+    border-color: var(--cinder-color-success-border);
+    background-color: var(--cinder-color-success-bg);
+  }
+
+  /* Banner presentation — full width, less rounding */
+  .cinder-capability-gate[data-cinder-presentation='banner'] {
+    border-radius: var(--cinder-radius-sm);
+    flex-direction: row;
+    align-items: center;
+    flex-wrap: wrap;
+  }
+
+  /* Callout presentation — indented, inline */
+  .cinder-capability-gate[data-cinder-presentation='callout'] {
+    border-inline-start-width: 4px;
+    border-radius: 0 var(--cinder-radius-md) var(--cinder-radius-md) 0;
+  }
+
+  .cinder-capability-gate__status {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-1);
+    flex: 1;
+  }
+
+  .cinder-capability-gate__feature {
+    font-weight: 600;
+    font-size: var(--cinder-text-sm);
+    /* No text-transform: `feature` is consumer-owned text — capitalizing it
+       would corrupt names like "MIDI" → "Midi" or "iOS" → "Ios". */
+  }
+
+  .cinder-capability-gate__state-text {
+    font-size: var(--cinder-text-sm);
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-capability-gate__content {
+    font-size: var(--cinder-text-sm);
+  }
+
+  .cinder-capability-gate__actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--cinder-space-1);
+    align-items: center;
+  }
+
+  .cinder-capability-gate__primary,
+  .cinder-capability-gate__fallback,
+  .cinder-capability-gate__dismiss {
+    display: inline-flex;
+    align-items: center;
+    padding: var(--cinder-space-1) var(--cinder-space-2);
+    border-radius: var(--cinder-radius-sm);
+    font-size: var(--cinder-text-sm);
+    font-weight: 500;
+    cursor: pointer;
+    border: 1px solid transparent;
+    text-decoration: none;
+  }
+
+  .cinder-capability-gate__primary {
+    background-color: var(--cinder-accent);
+    color: var(--cinder-accent-contrast);
+    border-color: var(--cinder-accent);
+  }
+
+  @media (hover: hover) {
+    .cinder-capability-gate__primary:hover {
+      background-color: var(--cinder-accent-hover);
+      border-color: var(--cinder-accent-hover);
+    }
+  }
+
+  .cinder-capability-gate__primary:focus-visible,
+  .cinder-capability-gate__fallback:focus-visible,
+  .cinder-capability-gate__dismiss:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    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);
+  }
+
+  .cinder-capability-gate__fallback {
+    background-color: transparent;
+    color: var(--cinder-text);
+    border-color: var(--cinder-border);
+  }
+
+  @media (hover: hover) {
+    .cinder-capability-gate__fallback:hover {
+      background-color: var(--cinder-surface-raised);
+    }
+  }
+
+  .cinder-capability-gate__dismiss {
+    background-color: transparent;
+    color: var(--cinder-text-muted);
+    margin-inline-start: auto;
+  }
+
+  @media (hover: hover) {
+    .cinder-capability-gate__dismiss:hover {
+      background-color: var(--cinder-surface-hover);
+      color: var(--cinder-text);
+    }
+  }
+}

package/src/components/capability-gate/capability-gate.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "capability-gate",
+  "import": "@lostgradient/cinder/capability-gate",
+  "examples": [
+    {
+      "id": "microphone",
+      "title": "Microphone permission gate",
+      "description": "Shows the capability gate in each state for a microphone permission request.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { CapabilityGate } from '@lostgradient/cinder/capability-gate';\n  import type { CapabilityGateState } from '@lostgradient/cinder/capability-gate';\n\n  let capabilityState = $state<CapabilityGateState>('permission-needed');\n  const needsAction = $derived(capabilityState === 'permission-needed');\n\n  const states: CapabilityGateState[] = [\n    'supported',\n    'unsupported',\n    'permission-needed',\n    'permission-denied',\n    'loading',\n    'unavailable',\n  ];\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; max-width: 28rem;\">\n  {#if needsAction}\n    <CapabilityGate\n      feature=\"Microphone\"\n      state={capabilityState}\n      primaryAction=\"Allow microphone\"\n      onPrimaryAction={() => {\n        capabilityState = 'supported';\n      }}\n      fallbackAction=\"Use text instead\"\n      onFallbackAction={() => {\n        capabilityState = 'unsupported';\n      }}\n    >\n      <p style=\"font-size: 0.875rem; color: var(--cinder-text-muted); margin: 0;\">\n        Microphone access is needed for voice input. Your audio is never stored or shared.\n      </p>\n    </CapabilityGate>\n  {:else}\n    <CapabilityGate feature=\"Microphone\" state={capabilityState} />\n  {/if}\n\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap;\">\n    {#each states as s (s)}\n      <Button\n        size=\"sm\"\n        variant={capabilityState === s ? 'secondary' : 'ghost'}\n        onclick={() => {\n          capabilityState = s;\n        }}\n      >\n        {s}\n      </Button>\n    {/each}\n  </div>\n</div>\n"
+    },
+    {
+      "id": "notifications",
+      "title": "Notifications permission gate (banner)",
+      "description": "A banner-style capability gate for browser notifications.",
+      "code": "<script lang=\"ts\">\n  import { CapabilityGate } from '@lostgradient/cinder/capability-gate';\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <CapabilityGate\n    feature=\"Notifications\"\n    state=\"permission-denied\"\n    variant=\"banner\"\n    fallbackAction=\"Enable in settings\"\n    fallbackHref=\"#\"\n    dismissAction=\"Dismiss\"\n  />\n  <CapabilityGate feature=\"Offline storage\" state=\"unsupported\" variant=\"callout\">\n    <p style=\"font-size: 0.875rem; color: var(--cinder-text-muted); margin: 0;\">\n      Your browser does not support offline storage. Some features may be limited.\n    </p>\n  </CapabilityGate>\n</div>\n"
+    }
+  ]
+}

package/src/components/capability-gate/capability-gate.svelte

@@ -0,0 +1,186 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category feedback
+   * @status alpha
+   * @purpose Present feature availability and next action for browser permission or support states, with accessible status text and focus management.
+   * @tag feedback
+   * @tag permission
+   * @tag notice
+   * @useWhen Surfacing that a feature requires a browser permission such as microphone or notifications.
+   * @useWhen Communicating that a feature is unsupported in the current browser with a clear fallback path.
+   * @avoidWhen Performing the actual feature detection or permission request — wire that in userland.
+   * @avoidWhen Storing permission state — CapabilityGate is a pure presentation component.
+   * @related alert, banner, callout, modal
+   */
+  export type {
+    CapabilityGateProps,
+    CapabilityGateState,
+    CapabilityGateVariant,
+  } from './capability-gate.types.ts';
+
+  /** Human-readable default status text per state. */
+  const DEFAULT_STATUS_TEXT: Record<string, string> = {
+    supported: 'Available',
+    unsupported: 'Not supported in this browser',
+    'permission-needed': 'Permission required',
+    'permission-denied': 'Permission was denied',
+    loading: 'Checking availability…',
+    unavailable: 'Not available',
+  };
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
+  import type { CapabilityGateProps } from './capability-gate.types.ts';
+
+  const KNOWN_STATES = [
+    'supported',
+    'unsupported',
+    'permission-needed',
+    'permission-denied',
+    'loading',
+    'unavailable',
+  ] as const;
+
+  let {
+    feature,
+    // Destructured off `state` to avoid svelte-check treating the bare identifier
+    // as the `$state` rune (the public prop name is still `state`).
+    state: stateProp,
+    variant = 'inline',
+    primaryAction,
+    onPrimaryAction,
+    fallbackAction,
+    fallbackHref,
+    onFallbackAction,
+    dismissAction,
+    onDismiss,
+    children,
+    class: customClassName,
+    ...rest
+  }: CapabilityGateProps = $props();
+
+  // Guard the runtime state: a plain-JS or malformed value falls back to
+  // `unavailable` (with a dev warning) rather than rendering an unknown
+  // data-cinder-state and the raw value as status text.
+  const availabilityState = $derived(
+    (KNOWN_STATES as readonly string[]).includes(stateProp) ? stateProp : 'unavailable',
+  );
+  $effect(() => {
+    if (!(KNOWN_STATES as readonly string[]).includes(stateProp)) {
+      devWarn(
+        `CapabilityGate: unknown state "${String(stateProp)}". Expected one of ${KNOWN_STATES.join(', ')}. Falling back to "unavailable".`,
+      );
+    }
+  });
+
+  let visible = $state(true);
+  let dismissButton: HTMLButtonElement | undefined = $state();
+
+  // Re-show the gate when the situation changes (e.g. permission-needed →
+  // permission-denied), so a previous dismissal doesn't permanently hide a new,
+  // possibly more urgent state. Reads feature + stateProp to track them.
+  $effect(() => {
+    void feature;
+    void stateProp;
+    visible = true;
+  });
+
+  const statusText = $derived(DEFAULT_STATUS_TEXT[availabilityState] ?? availabilityState);
+  const isLoading = $derived(availabilityState === 'loading');
+  const isError = $derived(
+    availabilityState === 'permission-denied' || availabilityState === 'unsupported',
+  );
+  const isWarning = $derived(availabilityState === 'permission-needed');
+  const isSuccess = $derived(availabilityState === 'supported');
+
+  const resolvedVariant = $derived(
+    isError ? 'error' : isWarning ? 'warning' : isSuccess ? 'success' : 'info',
+  );
+
+  function handleDismiss() {
+    // Blur the dismiss button before it unmounts so focus moves to <body>
+    // predictably rather than being stranded on a detached node. The consumer
+    // owns where focus should land next (e.g. a trigger to re-open the gate) and
+    // can set it in `onDismiss` — the component cannot know the right target.
+    dismissButton?.blur();
+    visible = false;
+    onDismiss?.();
+  }
+</script>
+
+{#if visible}
+  <div
+    {...rest}
+    class={classNames('cinder-capability-gate', customClassName)}
+    data-cinder-state={availabilityState}
+    data-cinder-variant={resolvedVariant}
+    data-cinder-presentation={variant}
+  >
+    <!-- Status text announced to assistive technology. aria-busy lives on the
+         live region so a loading→ready transition is announced consistently. -->
+    <div
+      class="cinder-capability-gate__status"
+      role="status"
+      aria-live="polite"
+      aria-busy={isLoading ? 'true' : undefined}
+    >
+      <span class="cinder-capability-gate__feature">{feature}</span>
+      <span class="cinder-capability-gate__state-text">{statusText}</span>
+    </div>
+
+    {#if children}
+      <div class="cinder-capability-gate__content">
+        {@render children()}
+      </div>
+    {/if}
+
+    {#if primaryAction || fallbackAction || fallbackHref || dismissAction}
+      <div class="cinder-capability-gate__actions">
+        {#if primaryAction}
+          <button
+            type="button"
+            class="cinder-capability-gate__primary"
+            onclick={onPrimaryAction}
+            aria-label="{primaryAction} for {feature}"
+          >
+            {primaryAction}
+          </button>
+        {/if}
+
+        {#if fallbackHref}
+          <a
+            href={fallbackHref}
+            class="cinder-capability-gate__fallback"
+            aria-label="{fallbackAction ?? 'Alternative option'} for {feature}"
+          >
+            {fallbackAction ?? 'Alternative option'}
+          </a>
+        {:else if fallbackAction}
+          <button
+            type="button"
+            class="cinder-capability-gate__fallback"
+            onclick={onFallbackAction}
+            aria-label="{fallbackAction} for {feature}"
+          >
+            {fallbackAction}
+          </button>
+        {/if}
+
+        {#if dismissAction}
+          <button
+            bind:this={dismissButton}
+            type="button"
+            class="cinder-capability-gate__dismiss"
+            onclick={handleDismiss}
+            aria-label={dismissAction}
+          >
+            {dismissAction}
+          </button>
+        {/if}
+      </div>
+    {/if}
+  </div>
+{/if}

package/src/components/capability-gate/capability-gate.types.ts

@@ -0,0 +1,83 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Availability state for a browser feature or permission. */
+export type CapabilityGateState =
+  | 'supported'
+  | 'unsupported'
+  | 'permission-needed'
+  | 'permission-denied'
+  | 'loading'
+  | 'unavailable';
+
+/** Presentation style for the gate. */
+export type CapabilityGateVariant = 'inline' | 'banner' | 'callout';
+
+/** Props for the CapabilityGate component. */
+export type CapabilityGateProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'role'
+> & {
+  /** The feature being gated (used in accessible status text). */
+  feature: string;
+  /** Current availability state. */
+  state: CapabilityGateState;
+  /** Presentation variant. @default "inline" */
+  variant?: CapabilityGateVariant;
+  /** Label for the primary action button (e.g. "Allow access", "Enable notifications"). */
+  primaryAction?: string;
+  /** Called when the user clicks the primary action button. */
+  onPrimaryAction?: () => void;
+  /** Label for the fallback action (e.g. "Use a different method"). */
+  fallbackAction?: string;
+  /** Href for a fallback link (renders an anchor instead of a button). */
+  fallbackHref?: string;
+  /** Called when the user clicks the fallback action (only when no fallbackHref). */
+  onFallbackAction?: () => void;
+  /** Label for the dismiss action. When provided a dismiss button is rendered. */
+  dismissAction?: string;
+  /**
+   * Called when the user dismisses the gate. The gate unmounts itself on
+   * dismiss; move focus to a sensible target here (e.g. the control that
+   * re-opens the gate) — the component blurs the dismiss button first so focus
+   * is not stranded, but only the consumer knows the right next focus target.
+   */
+  onDismiss?: () => void;
+  /** Custom content rendered below the status text and before the actions. */
+  children?: Snippet;
+  /** Additional class names merged with `.cinder-capability-gate`. */
+  class?: string;
+};
+
+/**
+ * Cinder-specific props for CapabilityGate, used by the schema generator.
+ */
+export interface CapabilityGateSchemaProps {
+  /** The feature being gated. */
+  feature: string;
+  /** Current availability state. */
+  state: CapabilityGateState;
+  /**
+   * Presentation variant.
+   * @default "inline"
+   */
+  variant?: CapabilityGateVariant;
+  /** Label for the primary action button. */
+  primaryAction?: string;
+  /** Label for the fallback action. */
+  fallbackAction?: string;
+  /** Href for a fallback link. */
+  fallbackHref?: string;
+  /** Label for the dismiss action. */
+  dismissAction?: string;
+  /** Additional class names merged with `.cinder-capability-gate`. */
+  class?: string;
+  /** Called when the primary action button is activated. */
+  onPrimaryAction?: () => void;
+  /** Called when the fallback action button is activated. */
+  onFallbackAction?: () => void;
+  /** Called when the gate is dismissed. */
+  onDismiss?: () => void;
+  /** Custom content rendered below the status text and before the actions. */
+  children?: Snippet;
+}

package/src/components/capability-gate/index.ts

@@ -0,0 +1,10 @@
+import './capability-gate.css';
+import CapabilityGate from './capability-gate.svelte';
+
+export default CapabilityGate;
+export type {
+  CapabilityGateProps,
+  CapabilityGateState,
+  CapabilityGateVariant,
+} from './capability-gate.types.ts';
+export { CapabilityGate };

package/src/components/card/README.md

@@ -19,13 +19,14 @@ Surface container for grouping related content and actions into a distinct visua
 | Prop                 | Type                            | Required | Default | Description                                                                                                                                 |
 | -------------------- | ------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bodyTone`           | `"default"` \| `"muted"`        | no       | —       | Body surface treatment. `muted` renders a grey/inset body region.                                                                           |
-| `description`        | `string`                        | no       | —       |                                                                                                                                             |
+| `description`        | `string`                        | no       | —       | Optional subheading rendered as a paragraph below the title inside the header.                                                              |
 | `edgeToEdgeOnMobile` | `boolean`                       | no       | —       | Remove side borders/radius and bleed to the viewport edge on narrow screens.                                                                |
 | `footerTone`         | `"default"` \| `"muted"`        | no       | —       | Footer surface treatment. `muted` renders a grey/inset footer region.                                                                       |
 | `headingLevel`       | `2` \| `3` \| `4` \| `5` \| `6` | no       | —       | Heading level for the generated title. Defaults to `3`. Set this so the card title nests correctly within the surrounding document outline. |
-| `title`              | `string`                        | no       | —       |                                                                                                                                             |
+| `padding`            | `"none"` \| `"default"`         | no       | —       | Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image).                                                   |
+| `title`              | `string`                        | no       | —       | Primary heading text rendered inside the card's header region.                                                                              |
 | `variant`            | `"card"` \| `"well"`            | no       | —       | Visual container style. `card` is raised; `well` is flatter and inset.                                                                      |
-| `children`           | `(opaque)`                      | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |
+| `children`           | `(opaque)`                      | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |
 | `class`              | `(opaque)`                      | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                     |
 | `footer`             | `(opaque)`                      | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |
 | `header`             | `(opaque)`                      | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |

package/src/components/card/card.css

@@ -60,6 +60,10 @@
     background: var(--cinder-surface-inset);
   }
 
+  .cinder-card__body[data-cinder-padding='none'] {
+    padding: 0;
+  }
+
   .cinder-card[data-cinder-variant='well'] .cinder-card__body {
     background: var(--cinder-surface-inset);
   }

package/src/components/card/card.examples.json

@@ -15,6 +15,12 @@
       "description": "A card that bleeds to the viewport edge below the mobile breakpoint.",
       "code": "<script lang=\"ts\">\n  import { Card } from '@lostgradient/cinder/card';\n</script>\n\n<Card edgeToEdgeOnMobile>\n  <div\n    style=\"min-block-size: 8rem; border: 1px dashed var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: repeating-linear-gradient(-45deg, transparent, transparent 0.5rem, color-mix(in oklch, var(--cinder-border-muted), transparent 70%) 0.5rem, color-mix(in oklch, var(--cinder-border-muted), transparent 70%) 0.5625rem);\"\n  ></div>\n</Card>\n"
     },
+    {
+      "id": "flush-body",
+      "title": "Flush body (padding=\"none\")",
+      "description": "Pass padding=\"none\" to remove the body padding for full-bleed content such as an image or a data table.",
+      "code": "<script lang=\"ts\">\n  import { Card } from '@lostgradient/cinder/card';\n</script>\n\n<Card title=\"Full-bleed image card\" padding=\"none\">\n  <div\n    style=\"min-block-size: 8rem; background: var(--cinder-surface-inset); border-top: 1px solid var(--cinder-border-muted); display: flex; align-items: center; justify-content: center; color: var(--cinder-text-subtle); font-size: var(--cinder-text-sm);\"\n  >\n    full-bleed content area\n  </div>\n</Card>\n"
+    },
     {
       "id": "well-edge-to-edge-mobile",
       "title": "Well, edge-to-edge on mobile",

package/src/components/card/card.svelte

@@ -12,7 +12,13 @@
    * @avoidWhen Presenting a single key metric — use stat or stat-group instead.
    * @related surface, stat, stacked-list-item, section-heading
    */
-  export type { CardHeadingLevel, CardProps, CardTone, CardVariant } from './card.types.ts';
+  export type {
+    CardHeadingLevel,
+    CardPadding,
+    CardProps,
+    CardTone,
+    CardVariant,
+  } from './card.types.ts';
 </script>
 
 <script lang="ts">
@@ -31,6 +37,7 @@
     bodyTone = 'default',
     footerTone = 'default',
     edgeToEdgeOnMobile = false,
+    padding = 'default',
     ...rest
   }: CardProps = $props();
 
@@ -64,7 +71,7 @@
     </div>
   {/if}
 
-  <div class="cinder-card__body" data-cinder-tone={bodyTone}>
+  <div class="cinder-card__body" data-cinder-tone={bodyTone} data-cinder-padding={padding}>
     {@render children()}
   </div>
 

package/src/components/card/card.types.ts

@@ -2,6 +2,8 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type CardVariant = 'card' | 'well';
 export type CardTone = 'default' | 'muted';
+/** Controls body padding. `none` removes all padding for flush/full-bleed content. Future values like `compact` may be added. */
+export type CardPadding = 'default' | 'none';
 /** Heading level for the generated card title, so the document outline stays correct. */
 export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
 type CardBase = HTMLAttributes<HTMLDivElement> & {
@@ -14,6 +16,8 @@ type CardBase = HTMLAttributes<HTMLDivElement> & {
   footerTone?: CardTone;
   /** Remove side borders/radius and bleed to the viewport edge on narrow screens. */
   edgeToEdgeOnMobile?: boolean;
+  /** Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image). */
+  padding?: CardPadding;
 };
 /** Basic card with no generated header. */
 type CardPlain = CardBase & {
@@ -35,12 +39,14 @@ type CardWithHeader = CardBase & {
 };
 /** Card with a title/description string API — simpler for standard cards. */
 type CardWithTitle = CardBase & {
+  /** Primary heading text rendered inside the card's header region. */
   title: string;
   /**
    * Heading level for the generated title. Defaults to `3`. Set this so the
    * card title nests correctly within the surrounding document outline.
    */
   headingLevel?: CardHeadingLevel;
+  /** Optional subheading rendered as a paragraph below the title inside the header. */
   description?: string;
   children: Snippet;
   footer?: Snippet;

package/src/components/card/index.ts

@@ -2,5 +2,5 @@ import './card.css';
 import Card from './card.svelte';
 
 export default Card;
-export type { CardProps, CardTone, CardVariant } from './card.types.ts';
+export type { CardPadding, CardProps, CardTone, CardVariant } from './card.types.ts';
 export { Card };

package/src/components/chart.types.ts

@@ -39,17 +39,29 @@ export type ChartCartesianSeries = {
 };
 
 export type ChartSharedProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Accessible label for the chart. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Pixel height of the chart viewport. Default `280`. */
   height?: number;
+  /** Configuration for the x-axis label and tick formatting. */
   xAxis?: ChartAxisConfiguration;
+  /** Configuration for the y-axis label and tick formatting. */
   yAxis?: ChartAxisConfiguration;
+  /** Where to render the series legend relative to the chart. Default `top`. */
   legendPosition?: ChartLegendPosition;
+  /** IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`. */
   hiddenSeriesIds?: string[];
+  /** Whether the chart is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`. */
   maximumInteractivePoints?: number;
+  /** Custom class applied to the root element. */
   class?: string;
   empty?: Snippet;
   loadingContent?: Snippet;