@almadar/ui 5.25.1 → 5.26.1

package/dist/docs/index.d.cts

@@ -195,6 +195,28 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
 }
 declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Cross-cutting atom-level prop shapes shared across the design system.
+ */
+/**
+ * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
+ * names that every component in the design system understands.  Prefer this
+ * over a bare `string` for any `color` or `variant` prop.
+ */
+type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
+/**
+ * Concrete error-state shape read by display components (`error.message`,
+ * occasionally `error.stack`). Structurally assignable from the global `Error`,
+ * so existing call sites passing an `Error` keep working — this just gives the
+ * pattern extractor a readable field schema instead of the opaque `Error` global.
+ */
+type UiError = {
+    message: string;
+    name?: string;
+    code?: string;
+    stack?: string;
+};
+
 /**
  * Icon Atom Component
  *
@@ -211,6 +233,7 @@ declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAtt
 
 type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 type IconAnimation = 'spin' | 'pulse' | 'none';
+
 interface IconProps {
     /**
      * Lucide icon component (preferred for type-safe usage), OR a canonical
@@ -222,8 +245,8 @@ interface IconProps {
     name?: string;
     /** Size of the icon */
     size?: IconSize;
-    /** Color class (Tailwind color class) or 'inherit' for theme default */
-    color?: string;
+    /** Semantic palette token or an arbitrary Tailwind color class. */
+    color?: ColorToken | string;
     /** Animation type */
     animation?: IconAnimation;
     /** Additional CSS classes */
@@ -326,10 +349,10 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
 declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLSelectElement | HTMLInputElement | HTMLTextAreaElement>>;
 
 /**
- * DocSidebar Molecule Component
- *
- * A documentation navigation sidebar with collapsible category sections.
- * Composes from Box, VStack, HStack, Typography, and Icon atoms.
+ * DocSidebar — collapsible documentation navigation sidebar.
+ * Renders a nested item tree with expand/collapse per category and active-item
+ * highlighting. Not a generic nav; it owns doc-site-specific UX (uppercase
+ * category headers, indented children, active highlight).
  */
 
 interface DocSidebarItem {
@@ -414,20 +437,89 @@ declare const DocBreadcrumb: React.FC<DocBreadcrumbProps>;
  */
 declare const CODE_LANGUAGES: readonly ["text", "json", "javascript", "js", "typescript", "ts", "jsx", "tsx", "css", "markdown", "md", "bash", "shell", "sh", "yaml", "yml", "rust", "python", "py", "sql", "diff", "toml", "go", "graphql", "html", "xml", "orb", "lolo"];
 type CodeLanguage = (typeof CODE_LANGUAGES)[number];
-
-interface DocCodeBlockProps {
-    /** Code content to display */
+type CodeViewerMode = 'code' | 'diff';
+interface DiffLine {
+    type: 'add' | 'remove' | 'context';
+    content: string;
+    lineNumber?: number;
+}
+interface CodeViewerAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: 'primary' | 'secondary' | 'ghost';
+}
+interface CodeViewerFile {
+    label: string;
     code: string;
-    /** Programming language label */
     language?: CodeLanguage;
-    /** Optional title/filename shown in the header bar */
+}
+interface CodeBlockProps {
+    /** The code content to display */
+    code?: string;
+    /** Programming language for syntax highlighting */
+    language?: CodeLanguage;
+    /** Show the copy button */
+    showCopyButton?: boolean;
+    /** Show the language badge */
+    showLanguageBadge?: boolean;
+    /** Maximum height before scrolling */
+    maxHeight?: string | number;
+    /** Enable brace-based code folding of multi-line `{}`/`[]` blocks (default: true). */
+    foldable?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * When true, render an editable surface that composes a transparent `Textarea`
+     * over a Prism-highlighted overlay. The overlay re-tokenizes on each keystroke
+     * (driven from a local mirror of the textarea value), so users see syntax-highlighted
+     * code while still being able to type. Folding is skipped in editable mode.
+     *
+     * History: GAP-51 first-cut shipped plain (no-highlighting) editable text;
+     * GAP-77 (2026-04-12) added the Prism overlay layer.
+     *
+     * Default: false (existing read-only behavior unchanged).
+     */
+    editable?: boolean;
+    /**
+     * GAP-51: called with the new code on every keystroke when `editable === true`.
+     * Consumers should debounce + parse downstream — `CodeBlock` does not.
+     */
+    onChange?: (code: string) => void;
+    /**
+     * GAP-80: line-level error/warning highlights for editable mode.
+     * Map of 1-based line number → severity. The overlay paints a colored
+     * background on each line: error = red, warning = yellow. Pass undefined
+     * (default) to disable. The consumer is responsible for computing the
+     * path → line map from the schema + validation results.
+     */
+    errorLines?: Map<number, 'error' | 'warning'>;
+    /** Title shown in the toolbar */
     title?: string;
-    /** Show line numbers in the gutter */
+    /** Diff or plain-code display mode */
+    mode?: CodeViewerMode;
+    /** Pre-computed diff lines */
+    diff?: readonly DiffLine[];
+    /** Old source text — generates diff when combined with newValue */
+    oldValue?: string;
+    /** New source text — generates diff when combined with oldValue */
+    newValue?: string;
+    /** Show line numbers in code / diff mode */
     showLineNumbers?: boolean;
-    /** Additional class names */
-    className?: string;
+    /** Enable word-wrap in code / diff mode */
+    wordWrap?: boolean;
+    /** Multiple files shown as tabs */
+    files?: readonly CodeViewerFile[];
+    /** Action badges in the toolbar */
+    actions?: readonly CodeViewerAction[];
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Show copy button (viewer alias for showCopyButton) */
+    showCopy?: boolean;
 }
-declare function DocCodeBlock({ code, language, title, showLineNumbers, className, }: DocCodeBlockProps): react_jsx_runtime.JSX.Element;
+declare const CodeBlock: React.NamedExoticComponent<CodeBlockProps>;
 
 interface DocPaginationLink {
     label: string;
@@ -460,4 +552,4 @@ interface DocSearchProps {
 }
 declare function DocSearch({ placeholder, onSearch, className, }: DocSearchProps): react_jsx_runtime.JSX.Element;
 
-export { Box, Button, Card, Divider, DocBreadcrumb, type DocBreadcrumbItem, type DocBreadcrumbProps, DocCodeBlock, type DocCodeBlockProps, DocPagination, type DocPaginationProps, DocSearch, type DocSearchProps, type DocSearchResult, DocSidebar, type DocSidebarItem, type DocSidebarProps, DocTOC, type DocTOCItem, type DocTOCProps, HStack, Icon, Input, Typography, VStack };
+export { Box, Button, Card, Divider, DocBreadcrumb, type DocBreadcrumbItem, type DocBreadcrumbProps, CodeBlock as DocCodeBlock, type CodeBlockProps as DocCodeBlockProps, DocPagination, type DocPaginationProps, DocSearch, type DocSearchProps, type DocSearchResult, DocSidebar, type DocSidebarItem, type DocSidebarProps, DocTOC, type DocTOCItem, type DocTOCProps, HStack, Icon, Input, Typography, VStack };

package/dist/docs/index.d.ts

@@ -21,8 +21,8 @@ export { DocTOC } from '../components/core/molecules/DocTOC';
 export type { DocTOCProps, DocTOCItem } from '../components/core/molecules/DocTOC';
 export { DocBreadcrumb } from '../components/core/molecules/DocBreadcrumb';
 export type { DocBreadcrumbProps, DocBreadcrumbItem } from '../components/core/molecules/DocBreadcrumb';
-export { DocCodeBlock } from '../components/core/molecules/DocCodeBlock';
-export type { DocCodeBlockProps } from '../components/core/molecules/DocCodeBlock';
+export { CodeBlock as DocCodeBlock } from '../components/core/molecules/markdown/CodeBlock';
+export type { CodeBlockProps as DocCodeBlockProps } from '../components/core/molecules/markdown/CodeBlock';
 export { DocPagination } from '../components/core/molecules/DocPagination';
 export type { DocPaginationProps } from '../components/core/molecules/DocPagination';
 export { DocSearch } from '../components/core/molecules/DocSearch';