@lostgradient/cinder 0.1.0

package/src/components/toolbar/toolbar.svelte

@@ -0,0 +1,409 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category action
+   * @status stable
+   * @purpose Named grouping of related controls that implements the WAI-ARIA toolbar pattern with DOM-driven roving tabindex.
+   * @tag action
+   * @tag grouping
+   * @useWhen Rendering a row or column of related controls where the whole set should be one Tab stop and arrow keys should move between items.
+   * @useWhen Wrapping existing cinder controls such as Button, SegmentedControl, and NumberInput without adding toolbar-specific child APIs.
+   * @avoidWhen Building a static flex row of controls that should remain in ordinary Tab order — use inline, cluster, or button-group instead.
+   * @related button-group, segmented-control, number-input
+   */
+  export type { ToolbarOrientation, ToolbarProps } from './toolbar.types.ts';
+</script>
+
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import type { HTMLAttributes } from 'svelte/elements';
+  import { on } from 'svelte/events';
+
+  import { classNames } from '../../utilities/class-names.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
+  import { getFocusableIndex, handleRovingKeydown } from '../../utilities/roving-tabindex.ts';
+  import { useMutationObserver } from '../../utilities/use-mutation-observer.svelte.ts';
+  import type { ToolbarProps } from './toolbar.types.ts';
+
+  type EditableElement = HTMLInputElement | HTMLTextAreaElement | HTMLElement;
+  type ToolbarRuntimeProps = ToolbarProps & {
+    role?: unknown;
+    'aria-orientation'?: unknown;
+    onkeydown?: HTMLAttributes<HTMLDivElement>['onkeydown'];
+    onfocusin?: HTMLAttributes<HTMLDivElement>['onfocusin'];
+  };
+
+  const focusableSelector = [
+    'button',
+    'a[href]',
+    'input',
+    'select',
+    'textarea',
+    '[tabindex]',
+    '[data-cinder-toolbar-item]',
+  ].join(',');
+
+  let {
+    class: className,
+    orientation = 'horizontal',
+    children,
+    onkeydown: consumerOnKeyDown,
+    onfocusin: consumerOnFocusIn,
+    role: _role,
+    'aria-orientation': _ariaOrientation,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    ...rest
+  }: ToolbarRuntimeProps = $props();
+
+  let rootElement: HTMLDivElement | null = null;
+  let toolbarItems = $state<HTMLElement[]>([]);
+  let activeItem = $state<HTMLElement | null>(null);
+
+  const originalTabIndexes = new WeakMap<HTMLElement, string | null>();
+  let previousManagedItems = new Set<HTMLElement>();
+  let lastWarnedNameSource = '';
+
+  function isHTMLElement(value: Element | EventTarget | null): value is HTMLElement {
+    return value instanceof HTMLElement;
+  }
+
+  function isHiddenInput(element: HTMLElement): boolean {
+    return element instanceof HTMLInputElement && element.type === 'hidden';
+  }
+
+  function isEditableTarget(element: HTMLElement): element is EditableElement {
+    if (element instanceof HTMLTextAreaElement) return true;
+    if (element instanceof HTMLInputElement) {
+      return ![
+        'button',
+        'checkbox',
+        'file',
+        'hidden',
+        'image',
+        'radio',
+        'range',
+        'reset',
+        'submit',
+      ].includes(element.type);
+    }
+    return element.isContentEditable;
+  }
+
+  function isSpinButtonLike(element: HTMLElement): boolean {
+    if (element.getAttribute('role') === 'spinbutton') return true;
+    if (!(element instanceof HTMLInputElement)) return false;
+    return element.closest('.cinder-number-input') !== null;
+  }
+
+  function hasCollapsedSelectionAtBoundary(
+    element: HTMLElement,
+    direction: -1 | 1,
+  ): element is HTMLInputElement | HTMLTextAreaElement {
+    if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement))
+      return false;
+    if (typeof element.selectionStart !== 'number' || typeof element.selectionEnd !== 'number')
+      return false;
+    if (element.selectionStart !== element.selectionEnd) return false;
+    const valueLength = element.value.length;
+    return direction === -1 ? element.selectionStart === 0 : element.selectionEnd === valueLength;
+  }
+
+  function placeCaret(element: HTMLElement, placement: 'start' | 'end'): void {
+    if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) return;
+    if (typeof element.setSelectionRange !== 'function') return;
+    const position = placement === 'end' ? element.value.length : 0;
+    element.setSelectionRange(position, position);
+  }
+
+  function isCssHidden(element: HTMLElement): boolean {
+    const elementStyle = getComputedStyle(element);
+    if (elementStyle.display === 'none' || elementStyle.visibility === 'hidden') return true;
+
+    let current = element.parentElement;
+    while (current) {
+      if (getComputedStyle(current).display === 'none') return true;
+      current = current.parentElement;
+    }
+    return false;
+  }
+
+  function isDisabledByFieldset(element: HTMLElement): boolean {
+    const disabledFieldset = element.closest('fieldset[disabled]');
+    if (!disabledFieldset) return false;
+    const firstLegend = disabledFieldset.querySelector('legend');
+    return firstLegend ? !firstLegend.contains(element) : true;
+  }
+
+  function isEligibleToolbarItem(element: HTMLElement): boolean {
+    if (!rootElement || element === rootElement) return false;
+    if (!rootElement.contains(element)) return false;
+    if (isHiddenInput(element)) return false;
+    if (element.hasAttribute('hidden')) return false;
+    if (element.getAttribute('aria-hidden') === 'true') return false;
+    if (element.getAttribute('aria-disabled') === 'true') return false;
+    if ('disabled' in element && typeof (element as HTMLButtonElement).disabled === 'boolean') {
+      if ((element as HTMLButtonElement).disabled) return false;
+    }
+    if (element.closest('[hidden],[aria-hidden=\"true\"],[data-cinder-toolbar-exclude]'))
+      return false;
+    if (element.closest('[inert]')) return false;
+    if (isDisabledByFieldset(element)) return false;
+    if (isCssHidden(element)) return false;
+    const authoredTabIndex = element.getAttribute('tabindex');
+    if (
+      authoredTabIndex === '-1' &&
+      !previousManagedItems.has(element) &&
+      !element.hasAttribute('data-cinder-toolbar-item')
+    ) {
+      return false;
+    }
+    return true;
+  }
+
+  function getToolbarItems(): HTMLElement[] {
+    if (!rootElement) return [];
+    return Array.from(rootElement.querySelectorAll<HTMLElement>(focusableSelector)).filter(
+      (element) => isEligibleToolbarItem(element),
+    );
+  }
+
+  function getActiveIndex(items: HTMLElement[], preferredItem: HTMLElement | null): number {
+    if (preferredItem) {
+      const preferredIndex = items.indexOf(preferredItem);
+      if (preferredIndex >= 0) return preferredIndex;
+    }
+    return getFocusableIndex(-1, items.length);
+  }
+
+  function restoreDepartedItems(nextItems: HTMLElement[]): void {
+    const nextItemSet = new Set(nextItems);
+    for (const item of previousManagedItems) {
+      if (nextItemSet.has(item)) continue;
+      const original = originalTabIndexes.get(item);
+      if (original === null) item.removeAttribute('tabindex');
+      else if (original !== undefined) item.setAttribute('tabindex', original);
+      originalTabIndexes.delete(item);
+    }
+    previousManagedItems = nextItemSet;
+  }
+
+  function syncToolbarItems(preferredItem: HTMLElement | null = activeItem): void {
+    const items = getToolbarItems();
+    restoreDepartedItems(items);
+
+    if (items.length === 0) {
+      toolbarItems = [];
+      activeItem = null;
+      return;
+    }
+
+    for (const item of items) {
+      if (!originalTabIndexes.has(item)) {
+        originalTabIndexes.set(item, item.getAttribute('tabindex'));
+      }
+    }
+
+    const activeIndex = getActiveIndex(items, preferredItem);
+    const resolvedActiveItem = activeIndex >= 0 ? (items[activeIndex] ?? null) : null;
+
+    for (const [index, item] of items.entries()) {
+      const nextTabIndex = index === activeIndex ? 0 : -1;
+      if (item.tabIndex !== nextTabIndex) {
+        item.tabIndex = nextTabIndex;
+      }
+    }
+
+    toolbarItems = items;
+    activeItem = resolvedActiveItem;
+  }
+
+  function moveFocus(nextIndex: number, caretPlacement: 'start' | 'end'): void {
+    const nextItem = toolbarItems[nextIndex];
+    if (!nextItem) return;
+    activeItem = nextItem;
+    syncToolbarItems(nextItem);
+    nextItem.focus();
+    placeCaret(nextItem, caretPlacement);
+  }
+
+  function getCurrentToolbarIndex(target: HTMLElement): number {
+    return toolbarItems.indexOf(target);
+  }
+
+  function handleEditableEscape(target: HTMLElement): boolean {
+    if (!isEditableTarget(target)) return false;
+    const currentIndex = getCurrentToolbarIndex(target);
+    if (currentIndex < 0) return false;
+    const nextIndex =
+      currentIndex < toolbarItems.length - 1
+        ? currentIndex + 1
+        : currentIndex > 0
+          ? currentIndex - 1
+          : -1;
+    if (nextIndex < 0) return false;
+    moveFocus(nextIndex, nextIndex > currentIndex ? 'start' : 'end');
+    return true;
+  }
+
+  function handleToolbarKeyDown(event: KeyboardEvent): void {
+    consumerOnKeyDown?.(event as KeyboardEvent & { currentTarget: EventTarget & HTMLDivElement });
+    if (event.defaultPrevented) return;
+    if (!isHTMLElement(event.target)) return;
+
+    const target = event.target.closest<HTMLElement>(focusableSelector);
+    if (!target || !toolbarItems.includes(target)) return;
+
+    const currentIndex = getCurrentToolbarIndex(target);
+    if (currentIndex < 0) return;
+
+    const horizontal = orientation !== 'vertical';
+    const targetIsEditable = isEditableTarget(target);
+
+    if (event.key === 'Escape' && targetIsEditable) {
+      if (!handleEditableEscape(target)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      return;
+    }
+
+    if ((event.key === 'Home' || event.key === 'End') && targetIsEditable) {
+      return;
+    }
+
+    if (horizontal && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) {
+      if (
+        targetIsEditable &&
+        !hasCollapsedSelectionAtBoundary(target, event.key === 'ArrowLeft' ? -1 : 1)
+      ) {
+        return;
+      }
+    }
+
+    if (!horizontal && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+      if (targetIsEditable || isSpinButtonLike(target)) return;
+    }
+
+    if (horizontal && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+      return;
+    }
+
+    if (!horizontal && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) {
+      return;
+    }
+
+    const nextIndex = handleRovingKeydown(event, currentIndex, toolbarItems.length, {
+      horizontal,
+      vertical: !horizontal,
+    });
+    if (nextIndex === null || nextIndex === currentIndex) return;
+
+    event.preventDefault();
+    event.stopPropagation();
+    moveFocus(
+      nextIndex,
+      event.key === 'ArrowLeft' || event.key === 'ArrowUp' || event.key === 'End' ? 'end' : 'start',
+    );
+  }
+
+  function handleToolbarFocusIn(event: FocusEvent): void {
+    consumerOnFocusIn?.(event as FocusEvent & { currentTarget: EventTarget & HTMLDivElement });
+    if (!isHTMLElement(event.target)) return;
+    const target = event.target.closest<HTMLElement>(focusableSelector);
+    if (!target || !isEligibleToolbarItem(target)) return;
+    syncToolbarItems(target);
+  }
+
+  function resolveAccessibleNameSource(): string {
+    const inlineLabel = ariaLabel?.trim() ?? '';
+    const labelledBy = ariaLabelledBy?.trim() ?? '';
+    return inlineLabel || labelledBy;
+  }
+
+  function hasResolvedLabelledByText(): boolean {
+    if (!rootElement || !ariaLabelledBy) return false;
+    const identifiers = ariaLabelledBy
+      .split(/\s+/)
+      .map((value) => value.trim())
+      .filter(Boolean);
+    if (identifiers.length === 0) return false;
+    return identifiers.every((identifier) => {
+      const element = document.getElementById(identifier);
+      return element !== null && (element.textContent?.trim().length ?? 0) > 0;
+    });
+  }
+
+  function warnAboutAccessibleName(): void {
+    if (!rootElement) return;
+    const warningKey = `${ariaLabel ?? ''}|${ariaLabelledBy ?? ''}`;
+    if (warningKey === lastWarnedNameSource) return;
+
+    const inlineLabel = ariaLabel?.trim() ?? '';
+    if (inlineLabel.length > 0) return;
+    if (ariaLabelledBy?.trim() && hasResolvedLabelledByText()) return;
+
+    lastWarnedNameSource = warningKey;
+    devWarn(
+      '[cinder/Toolbar] rendered without a resolvable accessible name. Pass a non-empty `aria-label` or `aria-labelledby` that points to non-empty text.',
+    );
+  }
+
+  function toolbarSetup(node: HTMLDivElement) {
+    rootElement = node;
+
+    syncToolbarItems(untrack(() => activeItem));
+
+    const cleanupKeyboardListener = on(node, 'keydown', handleToolbarKeyDown, { capture: true });
+    const cleanupFocusInListener = on(node, 'focusin', handleToolbarFocusIn);
+
+    const detachMutationObserver = useMutationObserver(
+      () => {
+        syncToolbarItems(activeItem);
+        warnAboutAccessibleName();
+      },
+      {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: [
+          'aria-disabled',
+          'aria-hidden',
+          'aria-label',
+          'aria-labelledby',
+          'class',
+          'data-cinder-toolbar-exclude',
+          'data-cinder-toolbar-item',
+          'disabled',
+          'hidden',
+          'inert',
+          'style',
+          'type',
+        ],
+      },
+    )(node);
+
+    warnAboutAccessibleName();
+
+    return () => {
+      cleanupKeyboardListener();
+      cleanupFocusInListener();
+      detachMutationObserver?.();
+      rootElement = null;
+      restoreDepartedItems([]);
+    };
+  }
+</script>
+
+<div
+  {...rest}
+  {@attach toolbarSetup}
+  role="toolbar"
+  aria-label={ariaLabel}
+  aria-labelledby={ariaLabelledBy}
+  aria-orientation={orientation === 'vertical' ? 'vertical' : undefined}
+  class={classNames('cinder-toolbar', className)}
+  data-cinder-orientation={orientation}
+  data-cinder-name-source={resolveAccessibleNameSource()}
+>
+  {@render children()}
+</div>

package/src/components/toolbar/toolbar.types.ts

@@ -0,0 +1,59 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Visual layout direction for Toolbar and Toolbar.Group. */
+export type ToolbarOrientation = 'horizontal' | 'vertical';
+
+type ToolbarBaseProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'aria-labelledby' | 'aria-orientation' | 'class' | 'role' | 'children'
+> & {
+  /** Additional class merged with `.cinder-toolbar`. */
+  class?: string;
+  /** Layout direction for roving-key ownership and separator placement. */
+  orientation?: ToolbarOrientation;
+  /** Controls rendered inside the toolbar. */
+  children: Snippet;
+};
+
+/**
+ * Public Toolbar props.
+ * Requires an accessible name through either `aria-label` or `aria-labelledby`.
+ */
+export type ToolbarProps = ToolbarBaseProps &
+  (
+    | { 'aria-label': string; 'aria-labelledby'?: never }
+    | { 'aria-label'?: never; 'aria-labelledby': string }
+  );
+
+/** Toolbar.Group props. */
+export type ToolbarGroupProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-orientation' | 'class'
+> & {
+  /** Additional class merged with `.cinder-toolbar__group`. */
+  class?: string;
+  /** Visual layout direction for the group's children. Defaults to the parent Toolbar orientation. */
+  orientation?: ToolbarOrientation;
+  /** Group contents. */
+  children: Snippet;
+};
+
+/** Toolbar.Spacer props. */
+export type ToolbarSpacerProps = Omit<HTMLAttributes<HTMLDivElement>, 'aria-hidden' | 'class'> & {
+  /** Additional class merged with `.cinder-toolbar__spacer`. */
+  class?: string;
+  /** Positive flex-grow value used to push later groups away. */
+  flex?: number;
+};
+
+/** Schema-facing Toolbar props. */
+export interface ToolbarSchemaProps {
+  /**
+   * Layout direction for keyboard ownership and separator placement.
+   * @default "horizontal"
+   */
+  orientation?: ToolbarOrientation;
+  /** Additional class merged with `.cinder-toolbar`. */
+  class?: string;
+}

package/src/components/toolbar/toolbar.variables.json

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

package/src/components/toolbar/toolbar.variables.ts

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

package/src/components/tooltip/README.md

@@ -0,0 +1,45 @@
+# Tooltip
+
+Hover-and-focus triggered hint for terse controls, anchored to a focusable child element.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import Tooltip from '@lostgradient/cinder/tooltip';
+</script>
+
+<Tooltip text="Refresh data" describe={false}>
+  <button type="button" aria-label="Refresh data">R</button>
+</Tooltip>
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop        | Type                                           | Required | Default | Description                                                                                                                |
+| ----------- | ---------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`     | `string`                                       | no       | —       |                                                                                                                            |
+| `describe`  | `boolean`                                      | no       | —       | Whether to wire tooltip text to the trigger via aria-describedby.                                                          |
+| `placement` | `"top"` \| `"right"` \| `"bottom"` \| `"left"` | no       | —       |                                                                                                                            |
+| `text`      | `string`                                       | yes      | —       |                                                                                                                            |
+| `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. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/tooltip/index.ts

@@ -0,0 +1,6 @@
+import './tooltip.css';
+import Tooltip from './tooltip.svelte';
+
+export default Tooltip;
+export type { TooltipPlacement, TooltipProps } from './tooltip.types.ts';
+export { Tooltip };

package/src/components/tooltip/tooltip.css

@@ -0,0 +1,65 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  /* ========================================
+ * TOOLTIP
+ * ======================================== */
+
+  .cinder-tooltip-wrapper {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  /* ----------------------------------------
+ * Tooltip element
+ * ---------------------------------------- */
+
+  .cinder-tooltip {
+    position: fixed;
+    left: 0;
+    top: 0;
+    z-index: var(--cinder-z-tooltip, 50);
+
+    max-width: 16rem;
+    padding: var(--cinder-space-1-5) var(--cinder-space-2-5);
+
+    border-radius: var(--cinder-radius-md);
+    background: var(--cinder-text);
+    color: var(--cinder-surface);
+    font-size: var(--cinder-text-xs);
+    line-height: var(--cinder-leading-snug);
+    white-space: nowrap;
+
+    pointer-events: none;
+    user-select: none;
+
+    transition: opacity var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  .cinder-tooltip[data-cinder-position-ready='false'] {
+    visibility: hidden;
+    opacity: 0;
+  }
+
+  /* Visible state */
+  .cinder-tooltip[aria-hidden='false'] {
+    visibility: visible;
+    opacity: 1;
+  }
+
+  /* Hidden state */
+  .cinder-tooltip[aria-hidden='true'] {
+    visibility: hidden;
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  /* ----------------------------------------
+ * Reduced motion
+ * ---------------------------------------- */
+
+  @media (prefers-reduced-motion: reduce) {
+    .cinder-tooltip {
+      transition: none;
+    }
+  }
+}

package/src/components/tooltip/tooltip.examples.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "tooltip",
+  "import": "@lostgradient/cinder/tooltip",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic tooltip",
+      "description": "Hover or focus the trigger to show the tooltip text.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Tooltip } from '@lostgradient/cinder/tooltip';\n</script>\n\n<Tooltip text=\"This is a helpful explanation.\">\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>\n"
+    },
+    {
+      "id": "placements",
+      "title": "Tooltip placements",
+      "description": "Top, right, bottom, and left placement options.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Tooltip } from '@lostgradient/cinder/tooltip';\n</script>\n\n<div class=\"example-preview-row\" style=\"padding: 1rem;\">\n  <Tooltip text=\"Appears above\" placement=\"top\">\n    <Button variant=\"secondary\">Top</Button>\n  </Tooltip>\n  <Tooltip text=\"Appears to the right\" placement=\"right\">\n    <Button variant=\"secondary\">Right</Button>\n  </Tooltip>\n  <Tooltip text=\"Appears below\" placement=\"bottom\">\n    <Button variant=\"secondary\">Bottom</Button>\n  </Tooltip>\n  <Tooltip text=\"Appears to the left\" placement=\"left\">\n    <Button variant=\"secondary\">Left</Button>\n  </Tooltip>\n</div>\n"
+    },
+    {
+      "id": "transformed-ancestor",
+      "title": "Transformed ancestor anchoring",
+      "description": "Hover the trigger after scrolling the transformed preview shell to verify tooltip fixed-position anchoring.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Tooltip } from '@lostgradient/cinder/tooltip';\n</script>\n\n<div data-testid=\"transformed-ancestor-example\" style=\"display: grid; gap: 1rem; max-width: 40rem;\">\n  <p style=\"margin: 0;\">\n    The tooltip trigger sits inside a transformed card and an inner scroll container. Hover after\n    scrolling the viewport to confirm the tooltip still anchors to the button instead of the\n    wrapper.\n  </p>\n\n  <div\n    data-testid=\"transformed-shell\"\n    style=\"transform: translate3d(32px, 0, 0) scale(0.98); transform-origin: top left; padding: 1rem; border-radius: 1rem; background: var(--cinder-surface-raised); border: 1px solid var(--cinder-border);\"\n  >\n    <div\n      data-testid=\"transformed-scroll-container\"\n      style=\"overflow: auto; width: 28rem; height: 18rem; padding: 1.5rem; border-radius: 0.75rem; background: var(--cinder-surface);\"\n    >\n      <div style=\"width: 48rem; height: 30rem; padding-top: 10rem; padding-left: 12rem;\">\n        <Tooltip text=\"Transformed ancestor tooltip anchor\" placement=\"bottom\">\n          <span data-testid=\"transformed-tooltip-trigger\">\n            <Button variant=\"secondary\">Hover for anchored tooltip</Button>\n          </span>\n        </Tooltip>\n      </div>\n    </div>\n  </div>\n</div>\n"
+    }
+  ]
+}

package/src/components/tooltip/tooltip.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "text": {
+      "type": "string"
+    },
+    "placement": {
+      "enum": ["top", "right", "bottom", "left"]
+    },
+    "describe": {
+      "type": "boolean",
+      "description": "Whether to wire tooltip text to the trigger via aria-describedby."
+    },
+    "class": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["text"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet"
+      }
+    ]
+  }
+}

package/src/components/tooltip/tooltip.schema.ts

@@ -0,0 +1,33 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    text: {
+      type: 'string',
+    },
+    placement: {
+      enum: ['top', 'right', 'bottom', 'left'],
+    },
+    describe: {
+      type: 'boolean',
+      description: 'Whether to wire tooltip text to the trigger via aria-describedby.',
+    },
+    class: {
+      type: 'string',
+    },
+  },
+  additionalProperties: false,
+  required: ['text'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;