@zentauri-ui/zentauri-components 1.4.41 → 1.4.61

package/src/ui/search/search-suggestion-list.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import { Fragment } from "react";
+
+import { cn } from "../../lib/utils";
+import { searchSuggestionOptionDomId } from "./search-suggestion-utils";
+
+import type { SearchSuggestionListProps } from "./types";
+
+const rowClassName =
+  "flex w-full flex-col gap-0.5 rounded-lg px-3 py-2.5 text-left text-sm transition-colors hover:bg-white/5 focus-visible:bg-white/5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/50";
+
+export function SearchSuggestionList({
+  items,
+  onSelect,
+  activeId,
+  onActiveIdChange,
+  listboxId,
+  className,
+  listClassName,
+  emptyLabel,
+}: SearchSuggestionListProps) {
+  if (items.length === 0) {
+    return (
+      <div
+        data-slot="search-suggestion-list-empty"
+        className={cn("px-1 py-6 text-center text-sm text-slate-500", className)}
+      >
+        {emptyLabel ?? "No matches."}
+      </div>
+    );
+  }
+
+  const useListbox = Boolean(listboxId);
+
+  const rows: Array<{
+    item: (typeof items)[number];
+    showGroup: boolean;
+  }> = [];
+  let lastGroupSeen: string | undefined;
+  for (const item of items) {
+    const showGroup = Boolean(item.group && item.group !== lastGroupSeen);
+    if (item.group) {
+      lastGroupSeen = item.group;
+    }
+    rows.push({ item, showGroup });
+  }
+
+  return (
+    <nav
+      data-slot="search-suggestion-list"
+      aria-label="Search results"
+      className={cn("flex max-h-[min(50vh,360px)] flex-col gap-1 overflow-y-auto pr-1", className)}
+    >
+      <div
+        {...(useListbox
+          ? {
+              id: listboxId,
+              role: "listbox" as const,
+            }
+          : {})}
+        className={cn("flex flex-col gap-0.5", listClassName)}
+      >
+        {rows.map(({ item, showGroup }) => {
+          const isActive = activeId === item.id;
+          const optionDomId =
+            useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : undefined;
+          return (
+            <Fragment key={item.id}>
+              {showGroup ? (
+                <div
+                  role="presentation"
+                  className="sticky top-0 z-1 bg-slate-950/95 px-2 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-slate-500 backdrop-blur-sm"
+                >
+                  {item.group}
+                </div>
+              ) : null}
+              <button
+                type="button"
+                id={optionDomId}
+                role={useListbox ? "option" : undefined}
+                aria-selected={useListbox ? isActive : undefined}
+                data-active={isActive ? "" : undefined}
+                className={cn(rowClassName, isActive ? "bg-white/5" : null)}
+                onMouseEnter={() => onActiveIdChange?.(item.id)}
+                onFocus={() => onActiveIdChange?.(item.id)}
+                onClick={() => onSelect(item.id)}
+              >
+                <span className="font-medium text-slate-100">{item.label}</span>
+                {item.description ? (
+                  <span className="truncate text-xs text-slate-500">{item.description}</span>
+                ) : null}
+              </button>
+            </Fragment>
+          );
+        })}
+      </div>
+    </nav>
+  );
+}
+
+SearchSuggestionList.displayName = "SearchSuggestionList";
+

package/src/ui/search/search-suggestion-utils.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+
+import { searchSuggestionOptionDomId } from "./search-suggestion-utils";
+
+describe("searchSuggestionOptionDomId", () => {
+  it("prefixes listbox id and sanitizes item id", () => {
+    expect(searchSuggestionOptionDomId(":lb:", "/a/b")).toBe(":lb:_opt__a_b");
+  });
+});

package/src/ui/search/search-suggestion-utils.ts

@@ -0,0 +1,8 @@
+/**
+ * Builds a stable DOM id for a listbox option so `aria-activedescendant` on the combobox
+ * input can reference it. Safe for href-like `itemId` strings.
+ */
+export function searchSuggestionOptionDomId(listboxId: string, itemId: string): string {
+  const safe = itemId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${listboxId}_opt_${safe}`;
+}

package/src/ui/search/types.ts

@@ -0,0 +1,52 @@
+import type { InputHTMLAttributes, ReactNode, Ref } from "react";
+
+import type { VariantProps } from "class-variance-authority";
+
+import type { inputVariants } from "../inputs/variants";
+
+export type SearchBarProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  "size" | "children" | "role"
+> & {
+  value: string;
+  onValueChange?: (value: string) => void;
+  leadingSlot?: ReactNode;
+  inputClassName?: string;
+  appearance?: VariantProps<typeof inputVariants>["appearance"];
+  inputSize?: VariantProps<typeof inputVariants>["size"];
+  ring?: VariantProps<typeof inputVariants>["ring"];
+  /** When set, the input exposes combobox semantics wired to a `role="listbox"` with this id. */
+  comboboxListboxId?: string;
+  /** Element id of the active option (from `searchSuggestionOptionDomId`) for `aria-activedescendant`. */
+  comboboxActiveOptionId?: string;
+  /** Whether the suggestion list is visibly expanded (controls `aria-expanded`). */
+  comboboxExpanded?: boolean;
+  ref?: Ref<HTMLInputElement>;
+};
+
+export type SearchSuggestionItem = {
+  id: string;
+  label: string;
+  description?: string;
+  group?: string;
+};
+
+export type SearchSuggestionListProps = {
+  items: readonly SearchSuggestionItem[];
+  onSelect: (id: string) => void;
+  activeId?: string;
+  onActiveIdChange?: (id: string | undefined) => void;
+  /** Pass the same id as `comboboxListboxId` on `SearchBar` for ARIA wiring. */
+  listboxId?: string;
+  className?: string;
+  listClassName?: string;
+  emptyLabel?: ReactNode;
+};
+
+export type SearchFilterable = {
+  id: string;
+  label: string;
+  description?: string;
+  keywords?: readonly string[];
+  href?: string;
+};

package/src/ui/typography/blockquote-base.tsx

@@ -0,0 +1,39 @@
+import { forwardRef } from "react";
+
+import { cn } from "../../lib/utils";
+
+import type { BlockquoteProps } from "./types";
+import { typographyToneVariants } from "./variants";
+
+export const BlockquoteBase = (props: BlockquoteProps) => {
+  const {
+    tone,
+    attribution,
+    className,
+    children,
+    ref,
+    ...rest
+  } = props;
+
+  return (
+    <blockquote
+      ref={ref}
+      data-slot="typography-blockquote"
+      className={cn(
+        typographyToneVariants({ tone }),
+        "border-l-4 py-1 pl-4 italic",
+        className,
+      )}
+      {...rest}
+    >
+      <div className="space-y-2 leading-relaxed">{children}</div>
+      {attribution ? (
+        <footer className="mt-3 text-sm not-italic">
+          <cite>{attribution}</cite>
+        </footer>
+      ) : null}
+    </blockquote>
+  );
+};
+
+BlockquoteBase.displayName = "Blockquote";

package/src/ui/typography/blockquote.tsx

@@ -0,0 +1,8 @@
+import { BlockquoteBase } from "./blockquote-base";
+import type { BlockquoteProps } from "./types";
+
+export const Blockquote = (props: BlockquoteProps) => {
+  return <BlockquoteBase {...props} />;
+};
+
+Blockquote.displayName = "Blockquote";

package/src/ui/typography/code-block-base.tsx

@@ -0,0 +1,37 @@
+import { forwardRef } from "react";
+
+import { cn } from "../../lib/utils";
+
+import type { CodeBlockProps } from "./types";
+import { typographyToneVariants } from "./variants";
+
+export const CodeBlockBase = (props: CodeBlockProps) => {
+    const {
+      tone,
+      language,
+      className,
+      children,
+      ref,
+      ...rest
+    } = props;
+
+    const ariaLabel = language ? `Code sample (${language})` : "Code sample";
+
+    return (
+      <pre
+        ref={ref}
+        data-slot="typography-code-block"
+        aria-label={ariaLabel}
+        className={cn(
+          typographyToneVariants({ tone }),
+          "overflow-x-auto rounded-xl border border-white/10 bg-slate-950/80 p-4 text-sm leading-relaxed shadow-inner shadow-slate-950/40",
+          className,
+        )}
+        {...rest}
+      >
+        <code className="font-mono text-[0.95em] whitespace-pre-wrap wrap-break-word">{children}</code>
+      </pre>
+    );
+};
+
+CodeBlockBase.displayName = "CodeBlock";

package/src/ui/typography/code-block.tsx

@@ -0,0 +1,8 @@
+import { CodeBlockBase } from "./code-block-base";
+import type { CodeBlockProps } from "./types";
+
+export const CodeBlock = (props: CodeBlockProps) => {
+  return <CodeBlockBase {...props} />;
+};
+
+CodeBlock.displayName = "CodeBlock";

package/src/ui/typography/heading-base.tsx

@@ -0,0 +1,59 @@
+import { forwardRef } from "react";
+
+import { cn } from "../../lib/utils";
+
+import type { HeadingProps } from "./types";
+import {
+  headingLevelVariants,
+  typographyToneVariants,
+} from "./variants";
+
+const HEADING_TAGS = {
+  1: "h1",
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+} as const;
+
+export const HeadingBase = (props: HeadingProps) => {
+    const {
+      level,
+      displayLevel,
+      tone,
+      bold,
+      italic,
+      underline,
+      strikethrough,
+      ref,
+      className,
+      children,
+      ...rest
+    } = props;
+
+    const Tag = HEADING_TAGS[level];
+    const scale = displayLevel ?? level;
+
+    return (
+      <Tag
+        ref={ref}
+        data-slot="typography-heading"
+        data-level={level}
+        className={cn(
+          typographyToneVariants({ tone }),
+          headingLevelVariants({ level: scale }),
+          bold && "font-bold",
+          italic && "italic",
+          underline && "underline underline-offset-4",
+          strikethrough && "line-through",
+          className,
+        )}
+        {...rest}
+      >
+        {children}
+      </Tag>
+    );
+};
+
+HeadingBase.displayName = "Heading";

package/src/ui/typography/heading.tsx

@@ -0,0 +1,8 @@
+import { HeadingBase } from "./heading-base";
+import type { HeadingProps } from "./types";
+
+export const Heading = (props: HeadingProps) => {
+  return <HeadingBase {...props} />;
+};
+
+Heading.displayName = "Heading";

package/src/ui/typography/index.ts

@@ -0,0 +1,28 @@
+export { Heading } from "./heading";
+export { Text } from "./text";
+export { List, ListItem } from "./list";
+export { Blockquote } from "./blockquote";
+export { InlineCode } from "./inline-code";
+export { CodeBlock } from "./code-block";
+
+export type {
+  BlockquoteProps,
+  CodeBlockProps,
+  HeadingLevel,
+  HeadingProps,
+  InlineCodeProps,
+  ListItemProps,
+  ListProps,
+  TextElement,
+  TextProps,
+  TypographyTone,
+  UnorderedMarker,
+} from "./types";
+
+export {
+  headingLevelVariants,
+  orderedListVariants,
+  textSizeVariants,
+  typographyToneVariants,
+  unorderedListMarkerVariants,
+} from "./variants";

package/src/ui/typography/inline-code-base.tsx

@@ -0,0 +1,27 @@
+import { forwardRef } from "react";
+
+import { cn } from "../../lib/utils";
+
+import type { InlineCodeProps } from "./types";
+import { typographyToneVariants } from "./variants";
+
+export const InlineCodeBase = (props: InlineCodeProps) => {
+    const { tone, className, children, ref, ...rest } = props;
+
+    return (
+      <code
+        ref={ref}
+        data-slot="typography-inline-code"
+        className={cn(
+          typographyToneVariants({ tone }),
+          "rounded-md border border-white/10 bg-white/6 px-1.5 py-0.5 font-mono text-[0.925em] font-normal",
+          className,
+        )}
+        {...rest}
+      >
+        {children}
+      </code>
+    );
+};
+
+InlineCodeBase.displayName = "InlineCode";

package/src/ui/typography/inline-code.tsx

@@ -0,0 +1,8 @@
+import { InlineCodeBase } from "./inline-code-base";
+import type { InlineCodeProps } from "./types";
+
+export const InlineCode = (props: InlineCodeProps) => {
+  return <InlineCodeBase {...props} />;
+};
+
+InlineCode.displayName = "InlineCode";

package/src/ui/typography/list-base.tsx

@@ -0,0 +1,88 @@
+import { cn } from "../../lib/utils";
+
+import type { ListProps, ListItemProps } from "./types";
+import {
+  orderedListVariants,
+  typographyToneVariants,
+  unorderedListMarkerVariants,
+} from "./variants";
+
+export function ListBase(props: ListProps) {
+  if ("ordered" in props && props.ordered === true) {
+    const {
+      tone,
+      className,
+      children,
+      ref,
+      ordered,
+      marker,
+      ...rest
+    } = props;
+
+    void ordered;
+    void marker;
+
+    return (
+      <ol
+        ref={ref}
+        data-slot="typography-list"
+        data-list-type="ordered"
+        className={cn(
+          typographyToneVariants({ tone }),
+          orderedListVariants(),
+          className,
+        )}
+        {...rest}
+      >
+        {children}
+      </ol>
+    );
+  }
+
+  const {
+    marker = "disc",
+    tone,
+    className,
+    children,
+    ref,
+    ordered,
+    ...rest
+  } = props;
+
+  void ordered;
+
+  return (
+    <ul
+      ref={ref}
+      data-slot="typography-list"
+      data-list-type="unordered"
+      className={cn(
+        typographyToneVariants({ tone }),
+        unorderedListMarkerVariants({ marker }),
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </ul>
+  );
+}
+
+ListBase.displayName = "List";
+
+export function ListItemBase(props: ListItemProps) {
+  const { className, children, ref, ...rest } = props;
+
+  return (
+    <li
+      ref={ref}
+      data-slot="typography-list-item"
+      className={cn("leading-relaxed", className)}
+      {...rest}
+    >
+      {children}
+    </li>
+  );
+}
+
+ListItemBase.displayName = "ListItem";

package/src/ui/typography/list.tsx

@@ -0,0 +1,15 @@
+import type { ListProps } from "./types";
+
+import { ListBase, ListItemBase } from "./list-base";
+
+export const ListItem = ListItemBase;
+
+function ListRoot(props: ListProps) {
+  return <ListBase {...props} />;
+}
+
+export const List = Object.assign(ListRoot, {
+  Item: ListItem,
+});
+
+ListRoot.displayName = "List";

package/src/ui/typography/text-base.tsx

@@ -0,0 +1,43 @@
+import { cn } from "../../lib/utils";
+
+import type { TextProps } from "./types";
+import { textSizeVariants, typographyToneVariants } from "./variants";
+
+export const TextBase = (props: TextProps) => {
+    const {
+      as = "p",
+      size = "base",
+      tone,
+      bold,
+      italic,
+      underline,
+      strikethrough,
+      highlight,
+      className,
+      children,
+      ...rest
+    } = props;
+
+    const Component = as;
+
+    return (
+      <Component
+        data-slot="typography-text"
+        className={cn(
+          typographyToneVariants({ tone }),
+          textSizeVariants({ size }),
+          bold && "font-semibold",
+          italic && "italic",
+          underline && "underline underline-offset-2",
+          strikethrough && "line-through",
+          highlight && "rounded bg-amber-400/15 px-0.5",
+          className,
+        )}
+        {...rest}
+      >
+        {children}
+      </Component>
+    );
+};
+
+TextBase.displayName = "Text";

package/src/ui/typography/text.tsx

@@ -0,0 +1,8 @@
+import { TextBase } from "./text-base";
+import type { TextProps } from "./types";
+
+export const Text = (props: TextProps) => {
+  return <TextBase {...props} />;
+};
+
+Text.displayName = "Text";

package/src/ui/typography/types.ts

@@ -0,0 +1,90 @@
+import type { VariantProps } from "class-variance-authority";
+import type {
+  ComponentProps,
+  HTMLAttributes,
+  RefObject,
+} from "react";
+
+import type {
+  textSizeVariants,
+  typographyToneVariants,
+  unorderedListMarkerVariants,
+} from "./variants";
+
+export type TypographyTone = NonNullable<
+  VariantProps<typeof typographyToneVariants>["tone"]
+>;
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export type HeadingProps = Omit<
+  ComponentProps<"h1">,
+  "color"
+> & {
+  level: HeadingLevel;
+  /** Visual scale; defaults to `level`. */
+  displayLevel?: HeadingLevel;
+  tone?: TypographyTone;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  ref?: RefObject<HTMLHeadingElement>;
+};
+
+export type TextElement = "p" | "span" | "div" | "label";
+
+export type TextProps = Omit<HTMLAttributes<HTMLElement>, "color"> & {
+  as?: TextElement;
+  size?: NonNullable<VariantProps<typeof textSizeVariants>["size"]>;
+  tone?: TypographyTone;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  highlight?: boolean;
+};
+
+export type UnorderedMarker = NonNullable<
+  VariantProps<typeof unorderedListMarkerVariants>["marker"]
+>;
+
+export type ListProps =
+  | (Omit<ComponentProps<"ul">, "color"> & {
+      ordered?: false;
+      marker?: UnorderedMarker;
+      tone?: TypographyTone;
+    })
+  | (Omit<ComponentProps<"ol">, "color"> & {
+      ordered: true;
+      marker?: undefined;
+      tone?: TypographyTone;
+    });
+
+export type ListItemProps = ComponentProps<"li"> & {
+  ref?: RefObject<HTMLLIElement>;
+};
+
+export type BlockquoteProps = ComponentProps<"blockquote"> & {
+  tone?: TypographyTone;
+  /** Attribution label shown in a footer (distinct from the HTML `cite` URL attribute). */
+  attribution?: string;
+  ref?: RefObject<HTMLQuoteElement>;
+};
+
+export type InlineCodeProps = Omit<
+  ComponentProps<"code">,
+  "color"
+> & {
+  tone?: TypographyTone;
+};
+
+export type CodeBlockProps = Omit<
+  ComponentProps<"pre">,
+  "color"
+> & {
+  tone?: TypographyTone;
+  /** Hint for stacked highlighting stacks / aria-labels. */
+  language?: string;
+  ref?: RefObject<HTMLPreElement>;
+};